home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / Online / Term / Extras / Source / gtlayout-source.lha / gtlayout.doc < prev    next >
Text File  |  1996-10-20  |  124KB  |  3,671 lines
  1. TABLE OF CONTENTS
  2.  
  3. gtlayout.library/--background--
  4. gtlayout.library/--version--
  5. gtlayout.library/LT_Activate
  6. gtlayout.library/LT_BeginRefresh
  7. gtlayout.library/LT_BuildA
  8. gtlayout.library/LT_CatchUpRefresh
  9. gtlayout.library/LT_CreateHandleTagList
  10. gtlayout.library/LT_DeleteHandle
  11. gtlayout.library/LT_DeleteWindowLock
  12. gtlayout.library/LT_DisposeMenu
  13. gtlayout.library/LT_EndGroup
  14. gtlayout.library/LT_EndRefresh
  15. gtlayout.library/LT_Exit
  16. gtlayout.library/LT_FindMenuCommand
  17. gtlayout.library/LT_GetAttributesA
  18. gtlayout.library/LT_GetCode
  19. gtlayout.library/LT_GetIMsg
  20. gtlayout.library/LT_GetMenuItem
  21. gtlayout.library/LT_HandleInput
  22. gtlayout.library/LT_Init
  23. gtlayout.library/LT_LabelChars
  24. gtlayout.library/LT_LabelWidth
  25. gtlayout.library/LT_LayoutMenusA
  26. gtlayout.library/LT_LevelWidth
  27. gtlayout.library/LT_LockWindow
  28. gtlayout.library/LT_MenuControlTagList
  29. gtlayout.library/LT_NewA
  30. gtlayout.library/LT_NewLevelWidth
  31. gtlayout.library/LT_NewMenuTagList
  32. gtlayout.library/LT_NewMenuTemplate
  33. gtlayout.library/LT_PressButton
  34. gtlayout.library/LT_RebuildTagList
  35. gtlayout.library/LT_Refresh
  36. gtlayout.library/LT_ReplyIMsg
  37. gtlayout.library/LT_SetAttributesA
  38. gtlayout.library/LT_ShowWindow
  39. gtlayout.library/LT_UnlockWindow
  40. gtlayout.library/LT_UpdateStrings
  41. gtlayout.library/--background--               gtlayout.library/--background--
  42.  
  43.    NOTES
  44.     1. General information
  45.  
  46.     1.1 Purpose
  47.  
  48.     The GUI code included in this archive helps to create user interfaces
  49.     using gadtools.library with a minimum of effort. The code
  50.     automatically takes care of the font to be used, making the user
  51.     interface font independent. Localizing support is built right into
  52.     the code, just install a callback hook and pass numeric IDs for the
  53.     gadget labels: the code will invoke your hook in order to get the
  54.     text required. Keystroke activation of gadgets is also taken care
  55.     of, in fact the code will -- unless told not to do so -- assign keyboard
  56.     shortcuts to the gadgets created all on its own. Every effort has been
  57.     made to make the code reentrant, so it can be put into a shared library.
  58.     If a user interface does not fit onto a screen provisions are made to
  59.     choose a smaller font and to rescale the window contents until they fit.
  60.     Last but not least the user interface code offers transparent extensions
  61.     to the standard gadtools.library objects, such as LISTVIEW_KIND objects
  62.     which respond to double-clicks or STRING_KIND objects which can be used
  63.     to enter password text as they will not display the characters entered.
  64.  
  65.  
  66.     1.2 Distribution
  67.  
  68.     The code is *free*, you don't need to pay any money to use it, nor
  69.     do you need to quote my name in the documentation, the program or
  70.     anywhere else. You are allowed to make changes to the code, but if
  71.     you stumble across any bugs or even know how to fix them, please
  72.     let me know. It does not matter whether you intend to sell a program
  73.     to use the code, use the code in shareware, gift-ware, freeware or
  74.     etc.-ware programs: the code still remains royalty-free.
  75.  
  76.  
  77.     1.3 Caveats
  78.  
  79.     The code is pretty large, about 80K-100K bytes in size. Not all
  80.     gadtools.library type objects are supported, notably
  81.     GENERIC_KIND objects. The code is not as flexible as
  82.     gadtools.library, so certain things which are easily done using
  83.     gadtools.library may be pretty difficult or even impossible.
  84.     The code is written entirely in `C' and requires SAS/C to
  85.     compile. Some parts of the code are highly recursive; I haven't
  86.     tested how much stack they might require in certain cases,
  87.     but I recommend that you don't overuse the grouping feature.
  88.     The data structures required to create and maintain the
  89.     user interface are huge, a single window might require more
  90.     than 4K-6K of memory. Proportional font support only works
  91.     well starting with Kickstart v39 and up, v2.04 will probably
  92.     not look quite that pretty.
  93.  
  94.  
  95.     2. Programming
  96.  
  97.     2.1 Client libraries required for link library version
  98.  
  99.     You need to have SysBase and GadToolsBase initialized in order to make
  100.     use of the code, i.e. your code has to do
  101.     WaitPort()...GT_GetIMsg()...GT_ReplyIMsg all on its own. The code makes
  102.     use of the memory pools introduced in exec.library v39, but calls the
  103.     equivalent routines in amiga.lib. Note: as of this writing the pools
  104.     code in amiga.lib v40.14 is broken, so you need to link with Mike
  105.     Sinz' fixed pools.lib.
  106.  
  107.  
  108.     2.2 Invocation procedure
  109.  
  110.     The typical invocation procedure looks roughly like this:
  111.  
  112.        LT_Init();    // only for link library version
  113.        :
  114.        :
  115.           LT_CreateHandleTags();
  116.              LT_New();
  117.              :
  118.              :
  119.              LT_New();
  120.                 LT_Build();
  121.                    LT_HandleInput();
  122.           LT_DeleteHandle();
  123.        :
  124.        :
  125.        LT_Exit();    // only for link library version
  126.  
  127.     You need to call LT_Init() only once in your program, it will initialize
  128.     the libraries and global data structures required by the user interface
  129.     code. When you are finished with the user interface and your program is
  130.     about to exit you need to call LT_Exit() or memory will get lost.
  131.     Note that LT_Init() is not protected against multiple invocations. If
  132.     called repeatedly memory will get lost which can never be reclaimed.
  133.     However, LT_Exit() is protected against multiple invocations, you can
  134.     also call it before ever giving LT_Init() a call, but I doubt this
  135.     would make much sense. If you are using the shared gtlayout.library
  136.     no call to LT_Init()/LT_Exit() is necessary as these calls are already
  137.     wrapped into the library opening code.
  138.        Before you can actually start building a window layout a call to
  139.     LT_CreateHandleTags() needs to be made. You need to pass in a pointer
  140.     to the Screen your user interface window is to be opened on and,
  141.     optionally, a few tags to control the look and performance of the
  142.     interface. *Never* close the screen in question before calling
  143.     LT_DeleteHandle() or nasty things will happen. For public screens
  144.     the code will try to lock the screen in question. With the handle
  145.     LT_CreateHandleTags() returned you can call LT_New() to build the
  146.     user interface. When finished a call to LT_Build() will finally
  147.     open a window and place the gadgets inside. A pointer to the
  148.     Window created will be returned, ready to be used for the
  149.     WaitPort()...GT_GetIMsg()...LT_HandleInput()...GT_ReplyIMsg()
  150.     loop. When finished, a call to LT_DeleteHandle() will close the
  151.     window and release all the memory associated with it. The design
  152.     of the interface code is similar to the corresponding calls in
  153.     gadtools.library, i.e. you don't need to worry about LT_New()
  154.     failing to allocate memory for the objects required. When it comes
  155.     to LT_Build() the code will know about any trouble which would
  156.     show up during previous invocations of LT_New(). In essence,
  157.     if LT_Build() returns NULL something is wrong.
  158.  
  159.  
  160.     2.3 Hierarchic grouping
  161.  
  162.     The basic building block of the user interface is a group, either
  163.     a horizontal or a vertical group. Adding gadgets or other objects
  164.     to a horizontal group will place them side by side from left to
  165.     right. A vertical group causes objects to be place from top to
  166.     bottom in one straight line. Groups help to arrange objects
  167.     neatly stacked, centered and properly aligned with other
  168.     members of the group.
  169.  
  170.     MUCHO IMPORTANTE: there is a bug lurking in the code which I never
  171.     had the luck to find and fix. One would expect to create
  172.     user interface structures like this:
  173.  
  174.        <group start>
  175.           <button>
  176.           <list>
  177.           <group start>
  178.              <slider>
  179.              <text>
  180.           <group end>
  181.           <button>
  182.        <group end>
  183.  
  184.     However, it is in fact not possible to mix gadgets and groups.
  185.     Thus, the user interface structure would have to look like this:
  186.  
  187.        <group start>
  188.           <group start>
  189.              <button>
  190.              <list>
  191.           <group end>
  192.           <group start>
  193.              <slider>
  194.              <text>
  195.           <group end>
  196.           <group start>
  197.              <button>
  198.           <group end>
  199.        <group end>
  200.  
  201.     Or in other words: groups only mix with other groups.
  202.  
  203.     You build groups using three different object types. In this
  204.     context `object type' refers to a specific numeric value the
  205.     LT_New() routine knows which will cause it to add another leaf
  206.     to the user interface structure tree. Here is an example:
  207.  
  208.        struct LayoutHandle *Handle;
  209.  
  210.        if(Handle = LT_CreateHandleTags(NULL,
  211.           LAHN_AutoActivate,FALSE,
  212.        TAG_DONE))
  213.        {
  214.           struct Window *Window;
  215.  
  216.           LT_New(Handle,
  217.              LA_Type,      VERTICAL_KIND,  /* A vertical group. */
  218.              LA_LabelText, "Main group",   /* Group title text. */
  219.           TAG_DONE);
  220.           {
  221.              LT_New(Handle,
  222.                 LA_Type,      BUTTON_KIND, /* A plain button. */
  223.                 LA_LabelText, "A button",
  224.                 LA_ID,        11,
  225.              TAG_DONE);
  226.  
  227.              LT_New(Handle,
  228.                 LA_Type,      XBAR_KIND,   /* A separator bar. */
  229.              TAG_DONE);
  230.  
  231.              LT_New(Handle,
  232.                 LA_Type,      BUTTON_KIND, /* A plain button. */
  233.                 LA_LabelText, "Another button",
  234.                 LA_ID,        22,
  235.              TAG_DONE);
  236.  
  237.              LT_New(Handle,
  238.                 LA_Type,      END_KIND,    /* This ends the current group. */
  239.              TAG_DONE);
  240.           }
  241.  
  242.           if(Window = LT_Build(Handle,
  243.             LAWN_Title,     "Window title",
  244.             LAWN_IDCMP,     IDCMP_CLOSEWINDOW,
  245.             WA_CloseGadget, TRUE,
  246.           TAG_DONE))
  247.           {
  248.               struct IntuiMessage *Message;
  249.               ULONG                MsgQualifier,
  250.                                    MsgClass;
  251.               UWORD                MsgCode;
  252.               struct Gadget       *MsgGadget;
  253.               BOOL                 Done = FALSE;
  254.  
  255.               do
  256.               {
  257.                   WaitPort(Window->UserPort);
  258.  
  259.                   while(Message = GT_GetIMsg(Window->UserPort))
  260.                   {
  261.                      MsgClass     = Message->Class;
  262.                      MsgCode      = Message->Code;
  263.                      MsgQualifier = Message->Qualifier;
  264.                      MsgGadget    = Message->IAddress;
  265.  
  266.                      GT_ReplyIMsg(Message);
  267.  
  268.                      LT_HandleInput(Handle,MsgQualifier,&MsgClass,
  269.                          &MsgCode,&MsgGadget);
  270.  
  271.                      switch(MsgClass)
  272.                      {
  273.                         case IDCMP_CLOSEWINDOW:
  274.  
  275.                             Done = TRUE;
  276.                             break;
  277.  
  278.                         case IDCMP_GADGETUP:
  279.  
  280.                             switch(MsgGadget->GadgetID)
  281.                             {
  282.                                 case 11: printf("First gadget\n");
  283.                                          break;
  284.  
  285.                                 case 22: printf("Second gadget\n");
  286.                                          break;
  287.                             }
  288.  
  289.                             break;
  290.                      }
  291.                   }
  292.               }
  293.               while(!Done);
  294.           }
  295.  
  296.           LT_DeleteHandle(Handle);
  297.        }
  298.  
  299.     The example creates one single group, places a few objects inside,
  300.     calls the layout routine, handles the input and finally cleans
  301.     things up again. This example also shows that you *need* at
  302.     least one group in your tree (to form the root) in order to get
  303.     things to work.
  304.        The input loop requires you to call LT_HandleInput() in order
  305.     to get the user interface code to filter out certain events and
  306.     to update internal information. The data passed in must have
  307.     been processed via the gadtools.library routines. You *must not*
  308.     call LT_HandleInput() before GT_ReplyIMsg() is called since the
  309.     routine may call intuition.library and gadtools.library routines
  310.     which in turn might lead to a system lock-up if the message
  311.     has not been processed yet. The first thing to do after LT_HandleInput()
  312.     has done whatever was necessary to the data you passed in is
  313.     examine the MsgClass variable. The user interface code will
  314.     `fake' certain message events using the variables passed in,
  315.     *do not* use any other data gathered from the original
  316.     IntuiMessage. The MsgClass may include event types you did
  317.     not ask for, i.e. the IDCMP flags of the window opened
  318.     will be set according to the objects you added to the window.
  319.     Also, the IDCMP_IDCMPUPDATE message class will show up for
  320.     certain objects. More on this later in this document.
  321.  
  322.  
  323.     2.4 Setting and getting object attributes
  324.  
  325.     The mechanism to update and query object attributes does not
  326.     exactly match the familiar gadtools.library interface. In
  327.     fact, the routine to change gadget attributes will forward
  328.     the tagitem list passed in to gadtools.library/GT_SetGadgetAttrs().
  329.     On the other hand the routine to query object attributes does
  330.     not work like gadtools.library/GT_GetGadgetAttrs(). The
  331.     user interface code assumes that all objects it can handle and
  332.     create posess certain attributes unique to the type of the
  333.     object in question. For example, the unique attribute of a
  334.     STRING_KIND object would be a pointer to the string it
  335.     `contains'. The unique attribute of a SLIDER_KIND object is
  336.     the current slider position. The LT_GetAttributes() routine
  337.     will return this attribute, but also accept a tagitem list
  338.     to fill in for certain special tag values.
  339.  
  340.  
  341.     2.5 Extra data
  342.  
  343.     Once a LayoutHandle has been created the interface code will
  344.     provide you with a number of information concerning the screen
  345.     the handle has been attached to. This information includes
  346.     the DrawInfo structure of the screen, the VisualInfo data
  347.     and the Screen address. This information is read-only.
  348.  
  349.  
  350.     2.6 Menus
  351.  
  352.     With a LayoutHandle available a routine called LT_LayoutMenuTags()
  353.     will create a standard Intuition menu structure via gadtools.library
  354.     which can be passed to LT_Build(). Note that this
  355.     routine does not modify any data passed in, it does neither
  356.     attach the menu created to the LayoutHandle passed in,
  357.     nor does it change the NewMenu table.
  358.  
  359.  
  360.     2.7 Localization
  361.  
  362.     All object and menu creation routines support localization via
  363.     a Hook callback interface, i.e. you can pass a pointer to an
  364.     initialized Hook structure to LT_CreateHandleTags() which will
  365.     later be used to supply label and list text for objects
  366.     created. The Hook callback routine is called in the following
  367.     fashion:
  368.  
  369.        String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,LONG ID)
  370.          D0                            A0                         A2        A1
  371.  
  372.     Or in other words: a locale string ID is passed in, the routine is supposed
  373.     to look up the string to match this ID and to return it.
  374.  
  375.  
  376.     2.8 Object types to generate IDCMP_IDCMPUPDATE events
  377.  
  378.     Certain objects convey extra information which is merged into the `fake'
  379.     input stream passed to the client calling LT_HandleInput(). These objects
  380.     are:
  381.  
  382.        STRING_KIND
  383.        TEXT_KIND
  384.        PALETTE_KIND
  385.  
  386.           The user pressed the `select' button which belongs
  387.           to this gadget. The MsgGadget pointer indicates the
  388.           STRING_KIND/TEXT_KIND/PALETTE_KIND object the `select'
  389.           button belongs to.
  390.  
  391.        LISTVIEW_KIND
  392.  
  393.           The user double-clicked on an entry. The entry number
  394.           is returned in the MsgCode variable. The MsgGadget
  395.           pointer indicates the LISTVIEW_KIND object the user
  396.           has clicked on.
  397.  
  398.  
  399.     2.9 Keystroke activation
  400.  
  401.     Unless forbidden via the the LA_NoKey tag item the user interface
  402.     code will pick the keyboard shortcuts for all gadgets on its own.
  403.     The currently active global console keymap will be checked at the
  404.     time when LT_Init() is called in order to make sure subsequent
  405.     calls to LT_Build() will use only keys the user can press on
  406.     the keyboard. Double-dead keys are also excluded from the
  407.     table created. This avoids problems with gadget labels such as
  408.     "éééé" which would require the user to hit two keys in a row to
  409.     activate the gadget.
  410.        If the window created happens to feature a close gadget
  411.     pressing the `Esc' key will cause the client to receive
  412.     an IDCMP_CLOSEWINDOW event.
  413.        A single LISTVIEW_KIND object may receive special treatment
  414.     if the LALV_CursorKey tag is used: the user will be able to
  415.     operate the listview using the cursor keys. Note: this
  416.     will also keep the user interface code from choosing a
  417.     special keystroke from the gadget label.
  418.        The user will be able to operate a single BUTTON_KIND
  419.     object using the return key if the LABT_ReturnKey tag is
  420.     used. A recessed frame will be drawn around the button hit
  421.     box to indicate its special status.
  422.        Pressing the Tab key can be bound to operate a cycle or
  423.     mx kind object.
  424.  
  425.     3. Credits
  426.  
  427.     The original design is based upon the user interface layout code used by
  428.     `term' 3.1. I put the first version of the layout routines together back
  429.     in Summer 1993 when I wanted to write the follow-up to `term' v3.4.
  430.  
  431.     Martin Taillefer rewrote large parts of the code, added new routines and
  432.     generally improved the performance of the layout process. I owe Martin
  433.     much for the ideas he put into the library.
  434.  
  435.     Kai Iske, Christoph Feck, Stefan Becker, Michael Barsoom and Sven Stullich
  436.     helped to iron out the remaining bugs and piled up bug reports and
  437.     enhancement requests.
  438.  
  439. gtlayout.library/--version--                     gtlayout.library/--version--
  440.  
  441.    NOTES
  442.     This document describes gtlayout.library v5.12 or higher. Do not assume that
  443.     previous library releases support the same features.
  444.  
  445. gtlayout.library/LT_Activate                     gtlayout.library/LT_Activate
  446.  
  447.    NAME
  448.     LT_Activate -- Activate a string type gadget.
  449.  
  450.    SYNOPSIS
  451.     LT_Activate(Handle,ID);
  452.                   A0   D0
  453.  
  454.     VOID LT_Activate(LayoutHandle *,LONG);
  455.  
  456.    FUNCTION
  457.     The equivalent to intuition.library/ActivateGadget().
  458.  
  459.    INPUTS
  460.     Handle - Pointer to LayoutHandle structure.
  461.  
  462.     ID - ID of Gadget to activate.
  463.  
  464.    RESULT
  465.     none
  466.  
  467.    SEE ALSO
  468.     intuition.library/ActivateGadget
  469.  
  470. gtlayout.library/LT_BeginRefresh             gtlayout.library/LT_BeginRefresh
  471.  
  472.    NAME
  473.     LT_BeginRefresh -- Optimized window refreshing
  474.  
  475.    SYNOPSIS
  476.     LT_BeginRefresh(Handle)
  477.                       A0
  478.  
  479.    FUNCTION
  480.     If you wish to handle window refreshing all on your own, you
  481.     might want to use the LT_BeginRefresh...LT_EndRefresh pair
  482.     in your program. By default the user interface layout engine
  483.     will automatically intercept IDCMP_REFRESHWINDOW events and
  484.     react to them accordingly.
  485.  
  486.    INPUTS
  487.     Handle - Pointer to a LayoutHandle structure.
  488.  
  489.    RESULT
  490.     none
  491.  
  492.    SEE ALSO
  493.     intuition.library/BeginRefresh
  494.     intuition.library/EndRefresh
  495.     gtlayout.library/LT_EndRefresh
  496.  
  497. gtlayout.library/LT_BuildA                         gtlayout.library/LT_BuildA
  498.  
  499.    NAME
  500.     LT_BuildA -- turn the user interface specs into a window
  501.                  and gadgets.
  502.  
  503.    SYNOPSIS
  504.     Window = LT_BuildA(Handle,Tags);
  505.       D0                 A0    A1
  506.  
  507.     struct Window *LT_BuildA(LayoutHandle *,struct TagItem *);
  508.  
  509.     Window = LT_Build(Handle,...);
  510.  
  511.     struct Window *LT_Build(LayoutHandle *,...);
  512.  
  513.    FUNCTION
  514.     This is the big one. After building up a user interface specification
  515.     using LT_NewA() a call to LT_BuildA() will finally lay out the single
  516.     user interface elements, open a window and put the gadgets, etc.
  517.     inside.
  518.  
  519.     The code tries to fit all the gadgets into the window, but if it
  520.     runs out of space it will fall back to a different font and
  521.     rescale the user interface objects to match it. It will first
  522.     fall back onto the system default font. If unsuccessful it will
  523.     as a last resort try to use topaz.font/8.
  524.  
  525.     To make it easier to distinguish between different handles that
  526.     share the same Window->UserPort, the Window->UserData pointer
  527.     will point to the LayoutHandle that created it (V13).
  528.  
  529.         NOTE: Earlier library releases did not support this feature,
  530.             so be prepared to deal with Window->UserData == NULL.
  531.  
  532.    INPUTS
  533.     Handle - Pointer to a LayoutHandle structure.
  534.  
  535.     Tags - Pointer to TagItem list controlling window
  536.         and layout attributes.
  537.  
  538.  
  539.     All the tag values given are passed straight away to OpenWindowTags(),
  540.     see intuition.doc for more information.
  541.  
  542.     In addition to this a number of private tag values are supported:
  543.  
  544.     LAWN_Menu (struct Menu *) - The menu to attach to the window. The
  545.         IDCMP flags will be updated to include IDCMP_MENUPICK if this
  546.         tag is used.
  547.  
  548.     LAWN_MenuTemplate (struct NewMenu *) - A list of filled-in
  549.         NewMenu structures which will get passed straight through
  550.         to LT_NewMenuTemplate(). If a menu could be created, it will
  551.         be attached to the window. LT_DeleteHandle() will then later
  552.         automatically dispose of the menu. Please note that the window
  553.         may fail to open due to the menu layout going wrong. Separate
  554.         calls to LT_NewMenuTemplate() and LT_Build() may be a better
  555.         approach since it is easier to find out which process went
  556.         wrong. You will find a pointer to the menu attached to the
  557.         LayoutHandle in LayoutHandle->Menu. Please note that this
  558.         entry only exists in LayoutHandles created by gtlayout.library
  559.         v13 or higher. (V13)
  560.  
  561.             NOTE: This tag effectively overrides LAWN_Menu.
  562.  
  563.     LAWN_MenuTags (struct TagItem *) - A list of TagItems which
  564.         will get passed straight through to LT_NewMenuTagList().
  565.         Even if you don't ask for it, LT_Build() will pass
  566.         "LAMN_Handle,<Handle>" in for you, so any additional tags
  567.         specifying screen, fonts, etc. will be overridden. If a menu
  568.         could be created, it will be attached to the window.
  569.         LT_DeleteHandle() will then later automatically dispose of the
  570.         menu. Please note that the window may fail to open due to the
  571.         menu layout going wrong. Separate calls to LT_NewMenuTagList()
  572.         and LT_Build() may be a better approach since it is easier to
  573.         find out which process went wrong. You will find a pointer to the
  574.         menu attached to the LayoutHandle in LayoutHandle->Menu. Please note
  575.         that this entry only exists in LayoutHandles created by
  576.         gtlayout.library v13 or higher. (V13)
  577.  
  578.             NOTE: This tag effectively overrides LAWN_Menu and has
  579.                   precedence over LAWN_MenuTemplate.
  580.  
  581.     LAWN_UserPort (struct MsgPort *) - The MsgPort to use as the
  582.         window user port. The MsgPort will be attached using the
  583.         common ModifyIDCMP() method, closing the window will
  584.         first remove and reply all pending messages at this port.
  585.  
  586.     LAWN_Left (LONG) - The left edge position the window is to use.
  587.         This effectively overrides any horizontal alignment flags.
  588.  
  589.             NOTE: the code may choose to ignore this value if it finds
  590.                 that the window will not fit onto the screen unless
  591.                 the left edge position is changed.
  592.  
  593.     LAWN_Top (LONG) - The top edge position the window is to use.
  594.         This effectively overrides any vertical alignment flags.
  595.  
  596.             NOTE: the code may choose to ignore this value if it finds
  597.                 that the window will not fit onto the screen unless
  598.                 the top edge position is changed.
  599.  
  600.     LAWN_Zoom (BOOL) - Adds a zoom gadget to the window. Clicking
  601.         on this gadget will cause the window to shrink/zoom back
  602.         to its original position. This differs from the WA_Zoom
  603.         tag behaviour. When the window zooms back to its original
  604.         position the gadgets are automatically refreshed.
  605.         Default: FALSE
  606.  
  607.     LAWN_MaxPen (LONG) - The maximum rendering pen index your code
  608.         will use. Since you are -- with some restrictions -- allowed
  609.         to render into the window created you may want to avoid
  610.         silly side effects if drawing images or other colourful
  611.         textures which do not share the common user interface colours.
  612.         By default the layout code will change the maximum rendering
  613.         pen number for the window to include only the user interface
  614.         pen colours. This can, but need not disturb your own private
  615.         window rendering.
  616.         Look up graphics.library/SetMaxPen for more information.
  617.         Default: determined by looking up Screen->DrawInfo.dri_Pens
  618.  
  619.     LAWN_BelowMouse (BOOL) - This instructs the layout routine to
  620.         centre the window created -- if possible -- below the
  621.         mouse pointer. This effectively ignores any left edge,
  622.         top edge or alignment settings.
  623.         Default: FALSE
  624.  
  625.     LAWN_MoveToWindow (BOOL) - When the window is finally open the
  626.         user interface code will try to make sure the entire window
  627.         is visible on the screen, this may involve moving the
  628.         currently visible portion of an autoscrolling screen.
  629.         Default: TRUE
  630.  
  631.     LAWN_AutoRefresh (BOOL) - Handle IDCMP_REFRESHWINDOW events
  632.         automatically.
  633.         Default: TRUE
  634.  
  635.     LAWN_HelpHook (struct Hook *) - Hook code to invoke when the user
  636.         presses the "Help" key. See gtlayout.h for more information.
  637.         Default: NULL
  638.  
  639.     LAWN_Parent (struct Window *) - Parent window to centre the child
  640.         window in.
  641.         Default: NULL
  642.  
  643.     LAWN_BlockParent (BOOL) - Lock the parent window via LT_LockWindow()
  644.         until the child window is closed.
  645.  
  646.             NOTE: requires LAWN_Parent attribute.
  647.  
  648.         Default: FALSE
  649.  
  650.     LAWN_SmartZoom (BOOL) - Attach a zoom gadget to the window created.
  651.         When in zoomed state, the window will be as small as possible,
  652.         showing only the window title and window gadgets:
  653.  
  654.             NOTE: this tag implies LAWN_Zoom,TRUE
  655.  
  656.         Default: FALSE
  657.  
  658.     LAWN_Title (STRPTR) - The window title to use. Use this tag in
  659.         place of WA_Title or you will break the layout code.
  660.         Default: no title
  661.  
  662.     LAWN_Bounds (struct IBox *) - Bounds to centre the window in.
  663.         Default: NULL
  664.  
  665.     LAWN_ExtraWidth (LONG) - Extra width to add into the calculation
  666.         when opening the window.
  667.         Default: 0
  668.  
  669.     LAWN_ExtraHeight (LONG) - Extra height to add into the calculation
  670.         when opening the window.
  671.         Default: 0
  672.  
  673.     LAWN_IDCMP (ULONG) - Use this tag in place of WA_IDCMP or you
  674.         will break the object handling code.
  675.  
  676.     LAWN_AlignWindow (UWORD) - Alignment information for the window, must
  677.         be a mask made from the following bit values:
  678.  
  679.             ALIGNF_RIGHT - Align to screen right edge
  680.             ALIGNF_LEFT - Align to screen left edge
  681.             ALIGNF_TOP - Align to screen top edge
  682.             ALIGNF_BOTTOM - Align to screen bottom edge
  683.  
  684.         Unless forbidden (such as by passing ALIGNF_RIGHT|ALIGNF_TOP)
  685.         the window will be centered horizontally and/or vertically.
  686.  
  687.     LAWN_FlushLeft (BOOL) - Add no horizontal space surrounding the
  688.         objects the windows will hold. (V10)
  689.  
  690.     LAWN_FlushTop (BOOL) - Add no vertical space surrounding the
  691.         objects the windows will hold. (V10)
  692.  
  693.     LAWN_Show (BOOL) - Make the window visible when it is opened;
  694.         this may involve depth-arranging screens. (V10)
  695.            Default: FALSE
  696.  
  697.     LAWN_NoInitialRefresh (BOOL) - If set to TRUE, adds the
  698.         gadgets, but does not draw the window imagery. You need
  699.         to draw them later by calling gtlayout.library/LT_Refresh.
  700.         Default: FALSE
  701.  
  702.     LAWN_LimitWidth (UWORD) - Limit the width of the window to this
  703.         value. (V35)
  704.  
  705.     LAWN_LimitHeight (UWORD) - Limit the height of the window to this
  706.         value. (V35)
  707.  
  708.    RESULT
  709.     Window - Pointer to a Window structure.
  710.  
  711.    SEE ALSO
  712.        gtlayout.library/LT_Refresh
  713.        intuition.library/OpenWindow
  714.        intuition.library/OpenWindowTagList
  715.  
  716. gtlayout.library/LT_CatchUpRefresh         gtlayout.library/LT_CatchUpRefresh
  717.  
  718.    NAME
  719.     LT_CatchUpRefresh -- Repair the display after missing the
  720.                          Window refresh message (V34).
  721.  
  722.    SYNOPSIS
  723.     LT_CatchUpRefresh(Handle)
  724.                         A0
  725.  
  726.     VOID LT_CatchUpRefresh(LayoutHandle *);
  727.  
  728.    FUNCTION
  729.     In case an application missed an IDCMP_REFRESHWINDOW event
  730.     the display may be damaged and in need of repair. This can
  731.     happen if the ASL requester is attached to the window,
  732.     sharing its IDCMP with the Window. Any refresh events will then
  733.     go straight to nil. Call this routine if you believe that
  734.     you missed a refresh event. The display will be repaired only
  735.     if it is in need of repair, so there is no harm in calling it
  736.     if not actually necessary.
  737.  
  738.    INPUTS
  739.     Handle - Pointer to a LayoutHandle structure.
  740.  
  741.    RESULT
  742.     none
  743.  
  744.    SEE ALSO
  745.     gtlayout.library/LT_BeginRefresh
  746.     intuition.library/BeginRefresh
  747.     intuition.library/EndRefresh
  748.  
  749. gtlayout.library/LT_CreateHandleTagListtlayout.library/LT_CreateHandleTagList
  750.  
  751.    NAME
  752.     LT_CreateHandleTagList -- Allocate auxilary data required by LT_New()
  753.                               and LT_BuildA().
  754.  
  755.    SYNOPSIS
  756.     Handle = LT_CreateHandleTagList(Screen,Tags);
  757.       D0                              A0    A1
  758.  
  759.     LayoutHandle *LT_CreateHandleTagList(struct Screen *,struct TagItem *);
  760.  
  761.     Handle = LT_CreateHandleTags(Screen,...);
  762.  
  763.     struct LayoutHandle *LT_CreateHandleTags(struct Screen *,...);
  764.  
  765.    FUNCTION
  766.     Memory is allocated, tables are set up and data is collected
  767.     on a screen a user interface is to be opened on. This
  768.     involves calculating the screen font parameters.
  769.  
  770.    INPUTS
  771.     Screen - Pointer to the screen the user interface is to
  772.         use. Passing NULL will cause the default public
  773.         screen to be used.
  774.  
  775.             NOTE: if NULL is passed the default public screen
  776.                 will stay locked until LT_DeleteHandle()
  777.                 is called.
  778.  
  779.     Tags - Tag values to control certain aspects of the
  780.         user interface created.
  781.  
  782.  
  783.     Valid tags include:
  784.  
  785.     LAHN_AutoActivate (BOOL) - Set to TRUE if you want the interface
  786.         to always keep a string gadget active if possible. Hitting
  787.         the return key will then cause the next following string
  788.         gadget to get activated, either cycling through all the
  789.         string gadgets available or stopping at the next string
  790.         gadget to have the LAST_LastGadget attribute set.
  791.         Default: TRUE
  792.  
  793.     LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
  794.         events. (V13)
  795.         Default: TRUE
  796.  
  797.     LAHN_UserData (APTR) - Store user specific data in the
  798.         LayoutHandle->UserData entry.
  799.  
  800.             NOTE: This tag requires gtlayout.library v9 and the
  801.                 corresponding entry in the LayoutHandle exists
  802.                 only under gtlayout.library v9 and up. *NEVER*
  803.                 write to this entry, use LT_SetAttributes()
  804.                 instead.
  805.  
  806.     LAHN_LocaleHook (struct Hook *) - The hook to call when
  807.         locale string IDs are to be mapped to strings. The
  808.         hook function is called with the following parameters:
  809.  
  810.         String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
  811.           D0                            A0                         A2
  812.                           LONG ID)
  813.                                A1
  814.  
  815.         The function is to look up the string associated with the ID
  816.         passed in and return the string.
  817.         Default: no locale hook
  818.  
  819.     LAHN_TextAttr (struct TTextAttr *) - The text font to use when
  820.         creating the gadgets and objects.
  821.         Default: Screen->Font
  822.  
  823.     LAHN_CloningPermitted (BOOL) - If a window will not fit onto the
  824.         screen the user interface is intended for, the layout engine
  825.         will scale the interface data down while stepping down in
  826.         font size. If all this fails, the engine will open a custom
  827.         screen for the window; this process is called "cloning".
  828.         The LAHN_CloningPermitted tag controls whether the engine will
  829.         actually try to open the custom screen or just return NULL
  830.         when LT_Build fails.
  831.         Default: TRUE
  832.  
  833.     LAHN_EditHook (struct Hook *) - You can specify a default string
  834.         gadget editing hook to be used for all following string
  835.         gadgets. Your hook should obey the same rules that apply
  836.         to hooks passed via GTST_EditHook/GTIN_EditHook.
  837.         Default: NULL
  838.  
  839.     LAHN_ExactClone (BOOL) - This tag works in conjunction with the
  840.         LAHN_CloningPermitted tag. By default the layout engine will
  841.         try to replicate only the basic characteristics of the
  842.         screen the window was intended to open on. This may result
  843.         in a screen which uses less colours than the original
  844.         screen. You can force the engine to make an almost exact
  845.         clone of the original screen by passing the LAHN_ExactClone
  846.         tag with a value of TRUE.
  847.         Default: FALSE
  848.  
  849.     LAHN_MenuGlyphs (BOOL) - This tag will make the layout engine
  850.         fill in the AmigaGlyph and CheckGlyph entries of the
  851.         LayoutHandle if running under Kickstart 3.0 or higher.
  852.         The corresponding images will be scaled to fit the actual
  853.         screen aspect ratio values and can later be used for
  854.         menu layout.
  855.         Default: FALSE
  856.  
  857.     LAHN_Parent (struct Window *) - You can pass a pointer to the
  858.         parent window of the window you intend to open using
  859.         the user interface layout engine. The new window will
  860.         open inside the boundaries of the parent window. If the
  861.         size does not fit, it will be opened centered over the
  862.         parent window.
  863.         Default: NULL
  864.  
  865.     LAHN_BlockParent (BOOL) - This tag works in conjunction with the
  866.         LAHN_Parent tag. If in effect, will block the parent window
  867.         via LT_LockWindow until the new window is closed, after
  868.         which the parent window is unlocked again.
  869.         Default: FALSE
  870.  
  871.     LAHN_SimpleClone (BOOL) - This tag works in conjunction with the
  872.         LAHN_CloningPermitted tag. It will make the layout engine
  873.         forget most information about the original screen the
  874.         user interface was intended for. In short, it will open a
  875.         simple default screen for the interface.
  876.         Default: FALSE
  877.  
  878.     LAHN_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
  879.         of with LT_DeleteHandle() all variables maintained by the
  880.         input handling code will be flushed. For example, if you
  881.         would use the LA_STRPTR tag for STRING_KIND objects the
  882.         last string gadget contents would be copied into the buffer
  883.         pointed to by LA_STRPTR. If you do not want to use this
  884.         feature, disable it with "LAHN_ExitFlush,FALSE". (V9)
  885.         Default: TRUE
  886.  
  887.     LAHN_NoKeys (BOOL) - Use TRUE to tell the library not to pick
  888.         keyboard shortcuts all on its own. This works like calling
  889.         LT_New() for all objects with "LA_NoKey,TRUE,". (V26)
  890.  
  891.     LAHN_PubScreen (struct Screen *) - Pointer to public screen
  892.         window is to open on. Must be locked and open until you call
  893.         LT_Built().
  894.  
  895.     LAHN_PubScreenName (STRPTR) - Name of public screen to open window
  896.         on. The library will try to lock the named screen as soon as
  897.         you call LT_CreateHandle.
  898.  
  899.     LAHN_PubScreenFallBack (BOOL) - If the named public screen cannot
  900.         be found and you ask for it, the library will lock the default
  901.         public screen (default: TRUE).
  902.  
  903.    RESULT
  904.     Handle - Pointer to a LayoutHandle structure.
  905.  
  906. gtlayout.library/LT_DeleteHandle             gtlayout.library/LT_DeleteHandle
  907.  
  908.    NAME
  909.     LT_DeleteHandle -- Release storage space allocated by
  910.                        LT_CreateHandleTagList, closing windows,
  911.                        removing gadgets, etc.
  912.  
  913.    SYNOPSIS
  914.     LT_DeleteHandle(Handle);
  915.                       A0
  916.  
  917.     VOID LT_DeleteHandle(LayoutHandle *);
  918.  
  919.    FUNCTION
  920.     Windows and gadgets created by LT_CreateHandleTagList()
  921.     are removed, any associated memory is deallocated.
  922.  
  923.    INPUTS
  924.     Handle - Pointer to a LayoutHandle structure created
  925.         by LT_CreateHandleTaglist(). Passing NULL is
  926.         harmless.
  927.  
  928.    RESULT
  929.     none
  930.  
  931.    SEE ALSO
  932.     gtlayout.library/CreateHandleTagList
  933.  
  934. gtlayout.library/LT_DeleteWindowLock     gtlayout.library/LT_DeleteWindowLock
  935.  
  936.    NAME
  937.     LT_DeleteWindowLock -- Remove all locks from a window
  938.  
  939.    SYNOPSIS
  940.     LT_DeleteWindowLock(Window);
  941.                           A0
  942.  
  943.     VOID LT_DeleteWindowLock(struct Window *);
  944.  
  945.    FUNCTION
  946.     Before closing a locked window you should call this routine
  947.     which will remove all outstanding locks from it.
  948.  
  949.    INPUTS
  950.     Window - Pointer to window structure; passing NULL is
  951.     harmless.
  952.  
  953.    RESULT
  954.     none
  955.  
  956. gtlayout.library/LT_DisposeMenu               gtlayout.library/LT_DisposeMenu
  957.  
  958.    NAME
  959.     LT_DisposeMenu -- Release storage space allocated by
  960.                       LT_NewMenuTemplate or LT_NewMenuTagList (V11)
  961.  
  962.    SYNOPSIS
  963.     LT_DisposeMenu(Menu)
  964.                     A0
  965.  
  966.     VOID LT_DisposeMenu(struct Menu *);
  967.  
  968.    FUNCTION
  969.     Menus and MenuItems allocated by LT_NewMenuTemplate or
  970.     LT_NewMenuTagList are deallocated.
  971.  
  972.    INPUTS
  973.     Menu - Pointer to Menu structure as returned by
  974.         LT_NewMenuTemplate or LT_NewMenuTagList. Passing
  975.         NULL is harmless.
  976.  
  977.    RESULT
  978.     none
  979.  
  980.    SEE ALSO
  981.     gtlayout.library/LT_NewMenuTagList
  982.     gtlayout.library/LT_NewMenuTemplate
  983.  
  984. gtlayout.library/LT_EndGroup                     gtlayout.library/LT_EndGroup
  985.  
  986.    NAME
  987.     LT_EndGroup -- end a group declaration.
  988.  
  989.    SYNOPSIS
  990.     LT_EndGroup(Handle);
  991.                  A0
  992.  
  993.     VOID LT_EndGroup(LayoutHandle *);
  994.  
  995.    FUNCTION
  996.       This is just a short form of
  997.  
  998.            LT_New(Handle,
  999.                LA_Type, END_KIND,
  1000.            TAG_DONE);
  1001.  
  1002.       It helps to save (some) space.
  1003.  
  1004.    INPUTS
  1005.         Handle - Pointer to LayoutHandle.
  1006.  
  1007.    RESULT
  1008.     none
  1009.  
  1010.    SEE ALSO
  1011.     gtlayout.library/LT_New
  1012.  
  1013. gtlayout.library/LT_EndRefresh                 gtlayout.library/LT_EndRefresh
  1014.  
  1015.    NAME
  1016.     LT_EndRefresh -- Optimized window refreshing
  1017.  
  1018.    SYNOPSIS
  1019.     LT_EndRefresh(Handle)
  1020.                     A0
  1021.  
  1022.     VOID LT_EndRefresh(LayoutHandle *);
  1023.  
  1024.    FUNCTION
  1025.     If you wish to handle window refreshing all on your own, you
  1026.     might want to use the LT_BeginRefresh...LT_EndRefresh pair
  1027.     in your program. By default the user interface layout engine
  1028.     will automatically intercept IDCMP_REFRESHWINDOW events and
  1029.     react to them accordingly.
  1030.  
  1031.    INPUTS
  1032.     Handle - Pointer to a LayoutHandle structure.
  1033.  
  1034.    RESULT
  1035.     none
  1036.  
  1037.    SEE ALSO
  1038.     gtlayout.library/LT_BeginRefresh
  1039.     intuition.library/BeginRefresh
  1040.     intuition.library/EndRefresh
  1041.  
  1042. gtlayout.library/LT_Exit                             gtlayout.library/LT_Exit
  1043.  
  1044.    NAME
  1045.     LT_Exit -- Clean up user interface allocations
  1046.  
  1047.    SYNOPSIS
  1048.     LT_Exit();
  1049.  
  1050.     VOID LT_Exit(VOID);
  1051.  
  1052.    FUNCTION
  1053.     When you are finished with user interface creation and
  1054.     do not not need the code any more you should call this
  1055.     routine. It will free all the memory allocated by
  1056.     LT_Init(), close libraries, etc.
  1057.  
  1058.    INPUTS
  1059.     none
  1060.  
  1061.    RESULT
  1062.     none
  1063.  
  1064.    NOTES
  1065.     This function is not present in the shared library, only
  1066.     in the link library. You need not and cannot invoke it in
  1067.     the shared library.
  1068.  
  1069.    SEE ALSO
  1070.     gtlayout.library/LT_Init
  1071.  
  1072. gtlayout.library/LT_FindMenuCommand       gtlayout.library/LT_FindMenuCommand
  1073.  
  1074.    NAME
  1075.     LT_FindMenuCommand -- Get the menu/submenu item associated
  1076.                           with a rawkey event (V11)
  1077.  
  1078.    SYNOPSIS
  1079.     Item = LT_FindMenuCommand(Menu,Code,Qualifier,Gadget)
  1080.      D0                        A0  D0       D0      A1
  1081.  
  1082.     struct MenuItem *LT_FindMenuCommand(struct Menu *,
  1083.  
  1084.                          UWORD,ULONG,struct Gadget *);
  1085.  
  1086.    FUNCTION
  1087.     With the IntuiMessage data copied from a type IDCMP_RAWKEY message
  1088.     tries to find the MenuItem the event referred to.
  1089.  
  1090.    INPUTS
  1091.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1092.  
  1093.     Code - Value copied from IntuiMessage->Code
  1094.  
  1095.     Qualifier - Value copied from IntuiMessage->Qualifier
  1096.  
  1097.     Gadget - Value copied from IntuiMessage->IAddress
  1098.  
  1099.    RESULT
  1100.     Item - Pointer to the struct MenuItem * in question or NULL
  1101.         if none could be found
  1102.  
  1103.    SEE ALSO
  1104.     gtlayout.library/LT_NewMenuTagList
  1105.  
  1106. gtlayout.library/LT_GetAttributesA         gtlayout.library/LT_GetAttributesA
  1107.  
  1108.    NAME
  1109.     LT_GetAttributesA -- Inquire information on a gadget.
  1110.  
  1111.    SYNOPSIS
  1112.     Value = LT_GetAttributesA(Handle,ID,Tags);
  1113.       D0                        A0   D0  A1
  1114.  
  1115.     LONG LT_GetAttributesA(LayoutHandle *,LONG ID,struct TagItem *);
  1116.  
  1117.     Value = LT_GetAttributes(Handle,ID,...);
  1118.  
  1119.     LONG LT_GetAttributes(LayoutHandle *,LONG ID,...);
  1120.  
  1121.    FUNCTION
  1122.     All objects created by the user interface layout code posess
  1123.     certain unique properties. The LT_GetAttributes() function will
  1124.     will inquire this information and return it. The implementation
  1125.     differs from gadtools.library/GT_GetGadgetAttrs in that you
  1126.     can inquire only a small subset of the object properties possible
  1127.     via the taglist passed in.
  1128.  
  1129.    INPUTS
  1130.     Handle - Pointer to LayoutHandle structure.
  1131.  
  1132.     ID - ID number of the object to inquire information about. This
  1133.         is the same value you passed via LA_ID to LT_New() when
  1134.         you created this object.
  1135.  
  1136.     Tags - TagItem list to receive information about the object
  1137.         in question.
  1138.  
  1139.  
  1140.     LA_Left (LONG *) - Left edge of object.
  1141.  
  1142.     LA_Top (LONG *) - Top edge of object.
  1143.  
  1144.     LA_Width (LONG *) - Width of object.
  1145.  
  1146.     LA_Height (LONG *) - Height of object.
  1147.  
  1148.     LA_Chars (LONG *) - Width of object measured in character
  1149.         widths. (V9)
  1150.  
  1151.     LA_Lines (LONG *) - Height of object measured in character
  1152.         heights. (V9)
  1153.  
  1154.     LA_LabelLeft (LONG *) - Left edge of label text. (V9)
  1155.  
  1156.     LA_LabelTop (LONG *) - Top edge of label text. (V9)
  1157.  
  1158.     LABO_Object (Object *) - Returns a pointer to the BOOPSI object
  1159.         the BOOPSI_KIND object is based upon. (V10)
  1160.  
  1161.             NOTE: Don't unlink the object or dispose of it or
  1162.                 terrible things are bound to happen.
  1163.  
  1164.    RESULT
  1165.     The result depends on the object type:
  1166.  
  1167.         VERTICAL_KIND:
  1168.         HORIZONTAL_KIND:
  1169.  
  1170.             active page
  1171.  
  1172.         SCROLLER_KIND:
  1173.  
  1174.             current GTSC_Top value
  1175.  
  1176.         TAPEDECK_KIND:
  1177.  
  1178.             current LATD_Pressed value
  1179.  
  1180.         LEVEL_KIND:
  1181.  
  1182.             current LAVL_Level state
  1183.  
  1184.         CHECKBOX_KIND:
  1185.  
  1186.             current GTCB_Checked state
  1187.  
  1188.         LISTVIEW_KIND:
  1189.  
  1190.             current GTLV_Selected state
  1191.  
  1192.         MX_KIND:
  1193.  
  1194.             current GTMX_Active state
  1195.  
  1196.         CYCLE_KIND:
  1197.  
  1198.             current GTCY_Active state
  1199.  
  1200.         POPUP_KIND:
  1201.  
  1202.             current LAPU_Active state
  1203.  
  1204.         TAB_KIND:
  1205.  
  1206.             current LATB_Active state
  1207.  
  1208.         PALETTE_KIND:
  1209.  
  1210.             current GTPA_Color state
  1211.  
  1212.         SLIDER_KIND:
  1213.  
  1214.             current GTSL_Level state
  1215.  
  1216.         GAUGE_KIND:
  1217.  
  1218.             current LAGA_Percent state
  1219.  
  1220.         STRING_KIND:
  1221.  
  1222.             pointer to current string
  1223.  
  1224.         PASSWORD_KIND:
  1225.  
  1226.             pointer to current string
  1227.  
  1228.         INTEGER_KIND:
  1229.  
  1230.             number currently entered
  1231.  
  1232.         BOOPSI_KIND:
  1233.  
  1234.             whatever the object thinks is its
  1235.             current value
  1236.  
  1237. gtlayout.library/LT_GetCode                       gtlayout.library/LT_GetCode
  1238.  
  1239.    NAME
  1240.     LT_GetCode -- Easy raw key event to ANSI conversion.
  1241.  
  1242.    SYNOPSIS
  1243.     Key = LT_GetCode(Qualifier,Class,Code,Gadget);
  1244.      D0                  D0     D1    D2    A0
  1245.  
  1246.     LONG LT_GetCode(ULONG,ULONG,UWORD,struct Gadget *);
  1247.  
  1248.    FUNCTION
  1249.     The user interface layout engine can convert IDCMP_RAWKEY
  1250.     events into ANSI codes. Pass in the data you copied from
  1251.     the IntuiMessage here.
  1252.  
  1253.    INPUTS
  1254.     Qualifier - Copied from IntuiMessage->Qualifier
  1255.  
  1256.     Class - Copied from IntuiMessage->Class
  1257.  
  1258.     Code - Copied from IntuiMessage->Code
  1259.  
  1260.     Gadget - Copied from IntuiMessage->IAddress
  1261.  
  1262.    RESULT
  1263.     Key - ANSI code generated from the input data
  1264.         or -1 if no such code was to be generated.
  1265.  
  1266. gtlayout.library/LT_GetIMsg                       gtlayout.library/LT_GetIMsg
  1267.  
  1268.    NAME
  1269.     LT_GetIMsg -- Retrieve the next pending IntuiMessage
  1270.                   from the window associated with a
  1271.                   LayoutHandle.
  1272.  
  1273.    SYNOPSIS
  1274.     IntuiMessage = LT_GetIMsg(Handle);
  1275.          D0                     A0
  1276.  
  1277.     struct IntuiMessage *LT_GetIMsg(LayoutHandle *);
  1278.  
  1279.    FUNCTION
  1280.     This routine will handle most of the input loop for
  1281.     you. Just pass the pointer to the layout handle in,
  1282.     check if the result code is non-null, copy the data
  1283.     you need and reply the message via LT_ReplyIMsg().
  1284.  
  1285.     You will still need to wait for new input, as LT_GetIMsg
  1286.     will poll the MsgPort of the window.
  1287.  
  1288.     LT_GetIMsg() will try its best to distinguish between
  1289.     different LayoutHandles sharing the same Window->UserPort.
  1290.     If it finds that the window the message was sent to is
  1291.     using a different LayoutHandle, it will switch to using
  1292.     this handle (V13).
  1293.  
  1294.    INPUTS
  1295.     Handle - Pointer to LayoutHandle structure
  1296.  
  1297.    RESULT
  1298.     IntuiMessage - Pointer to IntuiMessage structure
  1299.  
  1300.    NOTES
  1301.     You *must not* make any assumptions about the contents
  1302.     of the IntuiMessage structure except for the following
  1303.     entries:
  1304.  
  1305.        Class
  1306.        Code
  1307.        Qualifier
  1308.        IAddress
  1309.  
  1310.     When finished, you must dispose the IntuiMessage via
  1311.     LT_ReplyIMsg or memory will be lost which can never
  1312.     be reclaimed.
  1313.  
  1314.     DO NOT CALL LT_HandleInput() ON THE DATA YOU RECEIVE
  1315.     FROM LT_GetIMsg() AS LT_GetIMsg() ALREADY DOES ALL THE
  1316.     MAGIC LT_HandleInput() OTHERWISE WOULD NEED TO DO!
  1317.     IF YOU STILL DO CALL LT_HandleInput() ON THE DATA YOU
  1318.     WILL RECEIVE `GHOST' EVENTS.
  1319.  
  1320.    SEE ALSO
  1321.     gtlayout.library/LT_ReplyIMsg
  1322.  
  1323. gtlayout.library/LT_GetMenuItem               gtlayout.library/LT_GetMenuItem
  1324.  
  1325.    NAME
  1326.     LT_GetMenuItem -- Get the menu/submenu item associated with an ID (V11)
  1327.  
  1328.    SYNOPSIS
  1329.     Item = LT_GetMenuItem(Menu,ID)
  1330.      D0                    A0  D0
  1331.  
  1332.     struct MenuItem *LT_GetMenuItem(struct Menu *,ULONG);
  1333.  
  1334.    FUNCTION
  1335.     This routine scans through all menu items associated with the
  1336.     menu and returns a pointer to the item associated with the
  1337.     given ID value.
  1338.  
  1339.    INPUTS
  1340.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1341.  
  1342.     ID - Unique ID of the item to find.
  1343.  
  1344.    RESULT
  1345.     Item - Pointer to the struct MenuItem * in question or NULL
  1346.         if none could be found
  1347.  
  1348.    SEE ALSO
  1349.     gtlayout.library/LT_NewMenuTagList
  1350.  
  1351. gtlayout.library/LT_HandleInput               gtlayout.library/LT_HandleInput
  1352.  
  1353.    NAME
  1354.     LT_HandleInput -- Filter IntuiMessage data.
  1355.  
  1356.    SYNOPSIS
  1357.     LT_HandleInput(Handle,Qualifier,Class,Code,Gadget);
  1358.                      A0      D0      A1    A2    A3
  1359.  
  1360.     VOID LT_HandleInput(LayoutHandle *,ULONG,ULONG *,
  1361.                         UWORD *,struct Gadget **);
  1362.  
  1363.    FUNCTION
  1364.     In order to keep track of user interface actions, such as
  1365.     keys getting pressed, sliders getting moved, etc. your
  1366.     code is to call LT_HandleInput() with data copied from the
  1367.     IntuiMessage it has just received and replied.
  1368.  
  1369.    INPUTS
  1370.     Handle - Pointer to a LayoutHandle structure.
  1371.  
  1372.     Qualifier - The Qualifier value copied from the
  1373.         IntuiMessage structure.
  1374.  
  1375.     Class - Pointer to the ULONG variable which holds the
  1376.         value copied from the Class entry of the
  1377.         IntuiMessage structure.
  1378.  
  1379.     Code - Pointer to the UWORD variable which holds the
  1380.         value copied from the Code entry of the
  1381.         IntuiMessage structure.
  1382.  
  1383.     Gadget - Pointer to the Gadget value copied from the
  1384.         IAddress entry of the IntuiMessage structure.
  1385.  
  1386.    RESULT
  1387.     none
  1388.  
  1389.    EXAMPLE
  1390.     struct IntuiMessage *IntuiMessage;
  1391.     ULONG Qualifier,Class;
  1392.     UWORD Code;
  1393.     struct Gadget *Gadget;
  1394.  
  1395.     for(;;)
  1396.     {
  1397.         WaitPort(Window->UserPort);
  1398.  
  1399.         while(IntuiMessage = GT_GetIMsg(Window->UserPort))
  1400.         {
  1401.             Class = IntuiMessage->Class;
  1402.             Code = IntuiMessage->Code;
  1403.             Qualifier = IntuiMessage->Qualifier;
  1404.             Gadget = IntuiMessage->Gadget;
  1405.  
  1406.             GT_ReplyIMsg(IntuiMessage);
  1407.  
  1408.             LT_HandleInput(Handle,Qualifier,&Class,&Code,&Gadget);
  1409.         }
  1410.     }
  1411.  
  1412.    NOTES
  1413.     For BOOPSI_KIND objects keystroke activation may lead to
  1414.     unexpected results. Your application will hear a IDCMP_GADGETUP
  1415.     event, the IntuiMessage->Code value will hold the ANSI key
  1416.     code of the key the user pressed.
  1417.  
  1418.     Do not call this routine before you have actually
  1419.     replied the IntuiMessage received or weird things
  1420.     may happen. This is not a suggestion, it's a threat.
  1421.  
  1422. gtlayout.library/LT_Init                             gtlayout.library/LT_Init
  1423.  
  1424.    NAME
  1425.     LT_Init -- Initialize user interface code.
  1426.  
  1427.    SYNOPSIS
  1428.     LT_Init();
  1429.  
  1430.     VOID LT_Init(VOID);
  1431.  
  1432.    FUNCTION
  1433.     You need to initialize the user interface code only once,
  1434.     so it can set up its internals, open libraries, etc.
  1435.     The code has to be initialized before any user interface
  1436.     creation can take place.
  1437.  
  1438.    NOTES
  1439.     This function is not present in the shared library, only
  1440.     in the link library. You need not and cannot invoke it in
  1441.     the shared library.
  1442.  
  1443.    SEE ALSO
  1444.     gtlayout.library/LT_Exit
  1445.  
  1446. gtlayout.library/LT_LabelChars                 gtlayout.library/LT_LabelChars
  1447.  
  1448.    NAME
  1449.     LT_LabelChars -- Calculate the width of a a string
  1450.                      according to the user interface font
  1451.                      associated with a LayoutHandle.
  1452.  
  1453.    SYNOPSIS
  1454.     Length = LT_LabelChars(Handle,Label);
  1455.       D0                     A0    A1
  1456.  
  1457.     LONG LT_LabelChars(struct LayoutHandle *,STRPTR);
  1458.  
  1459.    FUNCTION
  1460.     Calculates the width of a string according to the user
  1461.     interface font used. The width is then converted to a number
  1462.     of characters suitable for using with the LA_Chars tag
  1463.     item when calling LT_New().
  1464.  
  1465.     You can pass multi-line label texts to this routine,
  1466.     it will calculate the maximum length of the single
  1467.     lines. (V12)
  1468.  
  1469.    INPUTS
  1470.     Handle - Pointer to LayoutHandle structure.
  1471.  
  1472.     Label - Pointer to string.
  1473.  
  1474.    RESULT
  1475.     Length - Number of characters that are considered
  1476.         equivalent to the string length in pixels.
  1477.  
  1478. gtlayout.library/LT_LabelWidth                 gtlayout.library/LT_LabelWidth
  1479.  
  1480.    NAME
  1481.     LT_LabelWidth -- Calculate the width of a string according
  1482.                      to the user interface font used.
  1483.  
  1484.    SYNOPSIS
  1485.     Width = LT_LabelWidth(Handle,Label);
  1486.       D0                    A0    A1
  1487.  
  1488.     LONG LT_LabelWidth(LayoutHandle *,STRPTR);
  1489.  
  1490.    FUNCTION
  1491.     This routine calculates the width of strings in
  1492.     terms of pixels according to the user interface
  1493.     font associated with the LayoutHandle.
  1494.  
  1495.     You can pass multi-line label texts to this routine,
  1496.     it will calculate the maximum length of the single
  1497.     lines. (V12)
  1498.  
  1499.    INPUTS
  1500.     Handle - Pointer to LayoutHandle structure.
  1501.  
  1502.    RESULT
  1503.     Width - Width of the text string in pixels.
  1504.  
  1505. gtlayout.library/LT_LayoutMenusA             gtlayout.library/LT_LayoutMenusA
  1506.  
  1507.    NAME
  1508.     LT_LayoutMenusA -- Create a menu according to a template.
  1509.  
  1510.    SYNOPSIS
  1511.     Menu = LT_LayoutMenusA(Handle,Template,Tags);
  1512.      D0                      A0     A1      A2
  1513.  
  1514.     struct Menu *LT_LayoutMenusA(LayoutHandle *,struct NewMenu *,
  1515.  
  1516.         struct TagItem *);
  1517.  
  1518.     Menu = LT_LayoutMenus(Handle,Template,...);
  1519.  
  1520.     struct Menu *LT_LayoutMenus(LayoutHandle *,struct NewMenu *,...);
  1521.  
  1522.    FUNCTION
  1523.     Unlike the corresponding routines in gadtools.library
  1524.     LT_LayoutMenusA() will both create and layout a menu.
  1525.     Also included is locale support.
  1526.  
  1527.    INPUTS
  1528.     Handle - Pointer to LayoutHandle structure.
  1529.  
  1530.     Template - Address of a ready-to-use NewMenu table to
  1531.         create the menu from.
  1532.  
  1533.     Tags - Tagitem list to control menu attributes
  1534.  
  1535.     Tags:
  1536.  
  1537.     LAMN_FirstLabel (LONG) - Locale ID of the first string to
  1538.         use as a menu title/item/subitem label. This tag
  1539.         works in conjunction with LA_LastLabel.
  1540.  
  1541.     LAMN_LastLabel (LONG) - Locale ID of the last string to
  1542.         use as a menu title/item/subitem label. This tag
  1543.         works in conjunction with LA_FirstLabel. The code
  1544.         will loop through FirstLabel..LastLabel and assign
  1545.         the corresponding locale text for each ID to the
  1546.         NewMenu.nm_Label entries. Labels which are already
  1547.         initialized with NM_BARLABEL are skipped.
  1548.  
  1549.     LAMN_LabelTable (LONG *) - Pointer to an array of IDs
  1550.         to use for building the menu labels. This requires
  1551.         that a locale hook is provided with the layout handle.
  1552.         The array is terminated by -1.
  1553.  
  1554.    RESULT
  1555.     Menu - Pointer to a Menu structure. You can free this
  1556.            using gadtools.library/FreeMenus().
  1557.  
  1558. gtlayout.library/LT_LevelWidth                 gtlayout.library/LT_LevelWidth
  1559.  
  1560.    NAME
  1561.     LT_LevelWidth -- Determine the maximum width of a SLIDER_KIND
  1562.                      level string.
  1563.  
  1564.    SYNOPSIS
  1565.     Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
  1566.       D0                    A0        A1         A2     D0  D1    A3
  1567.  
  1568.                               MaxLen,FullCheck);
  1569.                                 A5      D2
  1570.  
  1571.     LONG LT_LevelWidth(LayoutHandle *,STRPTR,
  1572.                        LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
  1573.                        LONG *,BOOL);
  1574.  
  1575.    FUNCTION
  1576.     In order to make room for the level text displayed by a
  1577.     SLIDER_KIND object one needs to know how much space the
  1578.     longest level string will occupy. Otherwise, the level
  1579.     text may overwrite the gadget label text or the slider
  1580.     container. This routine will rattle through all possible
  1581.     slider settings (as given via the Min and the Max
  1582.     level values) and determine the longest label string
  1583.     according to the font used.
  1584.  
  1585.    INPUTS
  1586.     Handle - Pointer to a LayoutHandle structure, as returned by
  1587.         a call to LT_CreateHandleTags().
  1588.  
  1589.     FormatString - The sprintf() style formatting string to be used
  1590.         to format the slider level settings into text.
  1591.         This is the same string you would pass in via
  1592.         the GTSL_LevelFormat tag when creating the
  1593.         slider object.
  1594.         Default: "%lD" for systems which have locale.library
  1595.             installed, "%ld" otherwise.
  1596.  
  1597.     DispFunc - A pointer to the function to filter the slider level
  1598.         values. The result of this function will then be
  1599.         used to format a string into the slider level text.
  1600.         This is the same parameter you would pass in via
  1601.         the GTSL_DispFunc tag when creating the slider
  1602.         object.
  1603.  
  1604.             NOTE: the routine will be called with a NULL Gadget
  1605.                 parameter, make sure your code will handle
  1606.                 this nicely.
  1607.  
  1608.         Default: no display function
  1609.  
  1610.     Min - The smallest value the slider can be set to. This is
  1611.         same value you would pass in via GTSL_Min when creating
  1612.         the slider object.
  1613.  
  1614.     Max - The largest value the slider can be set to. This is
  1615.         same value you would pass in via GTSL_Max when creating
  1616.         the slider object.
  1617.  
  1618.     MaxWidth - Pointer to a place to store the width of the
  1619.         longest level string in pixels. If you pass
  1620.         in NULL instead of the address of a variable
  1621.         no harm will be done.
  1622.  
  1623.     MaxLen - Pointer to a place to store the length of the
  1624.         longest level string in characters. If you pass
  1625.         in NULL instead of the address of a variable
  1626.         no harm will be done.
  1627.  
  1628.     FullCheck - TRUE will cause the code to rattle through all
  1629.         possible slider settings, starting from the
  1630.         minimum value, ending at the maximum value.
  1631.         While this may be a good idea for a display
  1632.         function to map slider levels to text strings
  1633.         of varying length it might be a problem when
  1634.         it comes to display a range of numbers from
  1635.         1 to 40,000: the code will loop through
  1636.         40,000 iterations trying to find the longest
  1637.         string.
  1638.  
  1639.         FALSE will cause the code to calculate the
  1640.         longest level string based only on the
  1641.         minimum and the maximum value to check.
  1642.         While this is certainly a good a idea when
  1643.         it comes to display a range of numbers from
  1644.         1 to 40,000 as only two values will be
  1645.         checked the code may fail to produce
  1646.         accurate results for sliders using display
  1647.         functions mapping slider levels to strings.
  1648.  
  1649.    RESULT
  1650.     Index - The slider level which gives the longest
  1651.         level string.
  1652.  
  1653.    NOTES
  1654.     Some compilers have trouble passing parameters in A5. In such
  1655.     a case it is recommended to use gtlayout.library/LT_NewLevelWidth
  1656.     instead.
  1657.  
  1658.    SEE ALSO
  1659.     gtlayout.library/LT_NewLevelWidth
  1660.  
  1661. gtlayout.library/LT_LockWindow                 gtlayout.library/LT_LockWindow
  1662.  
  1663.    NAME
  1664.     LT_LockWindow -- Block user access to a window.
  1665.  
  1666.    SYNOPSIS
  1667.     LT_LockWindow(Window);
  1668.                     A0
  1669.  
  1670.     VOID LT_LockWindow(struct Window *);
  1671.  
  1672.    FUNCTION
  1673.     The window will get a wait mouse pointer attached and a blank
  1674.     Requester, preventing any user gadgets from getting used. The
  1675.     window minimum and maximum sizes are set to the current window
  1676.     size so the user will be unable to resize the window or click
  1677.     on the zoom gadget.
  1678.  
  1679.     This routine nests, multiple calls to LT_LockWindow() using the
  1680.     same window will increment a usage counter, so exactly the
  1681.     same number of calls to LT_UnlockWindow() will be required to
  1682.     unlock the window.
  1683.  
  1684.    INPUTS
  1685.     Window - Pointer to window structure; passign NULL is harmless.
  1686.  
  1687.    RESULT
  1688.     none
  1689.  
  1690.    NOTES
  1691.     Do not close the window you have locked unless all the
  1692.     outstanding locks are freed or memory will be lost which
  1693.     can never be reclaimed. Before you close the window,
  1694.     call gtlayout.library/LT_DeleteWindowLock.
  1695.  
  1696.    SEE ALSO
  1697.     gtlayout.library/LT_DeleteWindowLock
  1698.  
  1699. gtlayout.library/LT_MenuControlTagList gtlayout.library/LT_MenuControlTagList
  1700.  
  1701.    NAME
  1702.     LT_MenuControlTagList -- Manipulate menus, menu/submenu items (V11)
  1703.  
  1704.    SYNOPSIS
  1705.     LT_MenuControlTagList(Window,Menu,Tags)
  1706.                            A0   A1     A2
  1707.  
  1708.     VOID LT_MenuControlTagList(struct Window *,struct Menu *,struct TagItem *);
  1709.  
  1710.     VOID LT_MenuControlTags(struct Window *,struct Menu *,...);
  1711.  
  1712.    FUNCTION
  1713.     This routine provides a rather efficient way to set and to clear,
  1714.     to enable and to disable a number of menus, menu/submenu items
  1715.     all at once.
  1716.  
  1717.     In v18 this routine was modified to disconnect a menu strip
  1718.     from a window if it is about to change checkmark states. In
  1719.     earlier releases or if a single menu is attached to several
  1720.     windows it is recommended that you disconnect the menu from
  1721.     the windows it is attached to before you call this routine.
  1722.  
  1723.     As of v18 this routine is smart enough to handle menu
  1724.     mutual exclusion.
  1725.  
  1726.    INPUTS
  1727.     Window - Pointer to Window this menu is attached to. Starting with
  1728.              gtlayout.library v16 this parameter may be NULL.
  1729.  
  1730.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1731.  
  1732.     Tags - Pointer to a list of tagitem values, as found
  1733.            in gtlayout.h
  1734.  
  1735.  
  1736.     Tags:
  1737.  
  1738.     LAMN_ID (ULONG) - Unique ID of menu/menu item/submenu item to
  1739.         manipulate.
  1740.  
  1741.     LAMN_Checked (BOOL) - Set the checkmark state of the
  1742.         menu/submenu item.
  1743.  
  1744.     LAMN_Disabled (BOOL) - Set the availability state of the
  1745.         menu/menu item/submenu item.
  1746.  
  1747.     LAMN_FullMenuNum (UWORD) - Intuition menu number of
  1748.         menu/submenu item to manipulate. You would pass the
  1749.         result of the FULLMENUNUM() macro here for the
  1750.         item in question. (V30)
  1751.  
  1752.    RESULT
  1753.     none
  1754.  
  1755.    EXAMPLE
  1756.     The following tagitem list will clear the checkmark and
  1757.     disable the menu item associated with ID 5 and set the
  1758.     checkmark for the item associated with ID 6:
  1759.  
  1760.         LAMN_ID,         5,
  1761.           LAMN_Checked,  FALSE,
  1762.           LAMN_Disabled, TRUE,
  1763.         LAMN_ID,         6,
  1764.           LAMN_Checked,  TRUE,
  1765.         TAG_DONE
  1766.  
  1767.    BUGS
  1768.     In library versions up to and including v17.2 this routine
  1769.     is broken. It won't do any harm, it just doesn't do what you
  1770.     want it to do.
  1771.  
  1772.    SEE ALSO
  1773.     gtlayout.library/LT_NewMenuTagList
  1774.  
  1775. gtlayout.library/LT_NewA                             gtlayout.library/LT_NewA
  1776.  
  1777.    NAME
  1778.     LT_NewA -- Add a new object to the user interface tree.
  1779.  
  1780.    SYNOPSIS
  1781.     LT_NewA(Handle,Tags);
  1782.              A0    A1
  1783.  
  1784.     VOID LT_NewA(LayoutHandle *,struct TagItem *);
  1785.  
  1786.     LT_New(Handle,...);
  1787.  
  1788.     VOID LT_New(LayoutHandle *,...);
  1789.  
  1790.    FUNCTION
  1791.     LT_NewA() is the routine you use to build the user interface,
  1792.     you give layout directions, design groups, etc. and finally
  1793.     call LT_BuildA() to turn these specifications into a window.
  1794.  
  1795.    INPUTS
  1796.     Handle - Pointer to LayoutHandle structure.
  1797.  
  1798.  
  1799.     This routine will accept almost all create-time tag items
  1800.     gadtools.library/CreateGadget will handle. In addition to
  1801.     this there are a bunch of extra gadget objects and extra
  1802.     tag items supported:
  1803.  
  1804.     All object types:
  1805.  
  1806.         LA_Type (LONG) - Type of the object to create, must be
  1807.             one of the following:
  1808.  
  1809.                 TEXT_KIND
  1810.                 VERTICAL_KIND
  1811.                 HORIZONTAL_KIND
  1812.                 END_KIND
  1813.                 FRAME_KIND
  1814.                 BOX_KIND
  1815.                 SLIDER_KIND
  1816.                 LISTVIEW_KIND
  1817.                 INTEGER_KIND
  1818.                 STRING_KIND
  1819.                 PASSWORD_KIND
  1820.                 PALETTE_KIND
  1821.                 BUTTON_KIND
  1822.                 CHECKBOX_KIND
  1823.                 NUMBER_KIND
  1824.                 GAUGE_KIND
  1825.                 CYCLE_KIND
  1826.                 POPUP_KIND
  1827.                 TAB_KIND
  1828.                 MX_KIND
  1829.                 XBAR_KIND
  1830.                 YBAR_KIND
  1831.                 TAPEDECK_KIND
  1832.                 LEVEL_KIND
  1833.                 BOOPSI_KIND
  1834.                 BLANK_KIND (V36)
  1835.  
  1836.         LA_LabelText (STRPTR) - The object label text to use.
  1837.  
  1838.         LA_LabelID (LONG) - The locale text ID of the string to
  1839.             use as the object label text.
  1840.  
  1841.                 NOTE: LT_NewA() will fail if you forget
  1842.                     to select a hook with LAHN_LocaleHook
  1843.                     at LT_CreateHandleTagList.
  1844.  
  1845.         LA_ID (LONG) - The gadget ID to use for this object.
  1846.  
  1847.                 NOTE: User ID values *MUST* be greater than 0,
  1848.                       negative values are reserved for internal
  1849.                       use.
  1850.  
  1851.         LA_Chars (LONG) - The width of this object measured in
  1852.             characters. If each character of the user interface
  1853.             font is 8 pixels wide an object with LA_Chars set to
  1854.             10 will usually be 80 pixels wide.
  1855.  
  1856.         LA_LabelChars (LONG) - This forces the internal gadget
  1857.             label width the layout engine calculates during the
  1858.             layout pass to a specific value. Note: this does
  1859.             not work well with all objects. (V9)
  1860.  
  1861.         LA_LabelPlace (LONG) - Where to place the gadget label.
  1862.             Not all objects will support all label positions:
  1863.  
  1864.                 PLACE_LEFT - Place label text left of object
  1865.                 PLACE_RIGHT - Place label text right of object
  1866.                 PLACE_ABOVE - Place label text above object
  1867.                 PLACE_IN - Place label text in object
  1868.                 PLACE_BELOW - Place label text below object
  1869.  
  1870.         LA_ExtraSpace (BOOL) - Add extra vertical/horizontal
  1871.             space before this object.
  1872.             Default: FALSE
  1873.  
  1874.         LA_ExtraFat (BOOL) - Make this object a bit larger
  1875.             than its usual size.
  1876.             Default: FALSE
  1877.  
  1878.         LA_NoKey (BOOL) - Don't let the user interface choose
  1879.             a keyboard shortcut for this object.
  1880.             Default: FALSE
  1881.  
  1882.         LA_HighLabel (BOOL) - Use highlight pen when rendering
  1883.             the gadget label text.
  1884.             Default: FALSE
  1885.  
  1886.         LA_BYTE (BYTE *) - Pointer to the variable that holds
  1887.             the "current value" of the object. The layout engine
  1888.             will retrieve this value initially during the creation
  1889.             of the object and maintain it during its lifespan.
  1890.             This means you do not need to worry about checking
  1891.             the state of the object, the user interface layout
  1892.             engine will do it for you.
  1893.  
  1894.         LA_UBYTE (UBYTE *) - Pointer to the variable that holds
  1895.             the "current value" of the object. The layout engine
  1896.             will retrieve this value initially during the creation
  1897.             of the object and maintain it during its lifespan.
  1898.             This means you do not need to worry about checking
  1899.             the state of the object, the user interface layout
  1900.             engine will do it for you.
  1901.  
  1902.         LA_WORD (WORD *) - Pointer to the variable that holds
  1903.             the "current value" of the object. The layout engine
  1904.             will retrieve this value initially during the creation
  1905.             of the object and maintain it during its lifespan.
  1906.             This means you do not need to worry about checking
  1907.             the state of the object, the user interface layout
  1908.             engine will do it for you.
  1909.  
  1910.         LA_UWORD (UWORD *) - Pointer to the variable that holds
  1911.             the "current value" of the object. The layout engine
  1912.             will retrieve this value initially during the creation
  1913.             of the object and maintain it during its lifespan.
  1914.             This means you do not need to worry about checking
  1915.             the state of the object, the user interface layout
  1916.             engine will do it for you.
  1917.  
  1918.         LA_BOOL (BOOL *) - Pointer to the variable that holds
  1919.             the "current value" of the object. The layout engine
  1920.             will retrieve this value initially during the creation
  1921.             of the object and maintain it during its lifespan.
  1922.             This means you do not need to worry about checking
  1923.             the state of the object, the user interface layout
  1924.             engine will do it for you.
  1925.  
  1926.         LA_LONG (LONG *) - Pointer to the variable that holds
  1927.             the "current value" of the object. The layout engine
  1928.             will retrieve this value initially during the creation
  1929.             of the object and maintain it during its lifespan.
  1930.             This means you do not need to worry about checking
  1931.             the state of the object, the user interface layout
  1932.             engine will do it for you.
  1933.  
  1934.         LA_ULONG (ULONG *) - Pointer to the variable that holds
  1935.             the "current value" of the object. The layout engine
  1936.             will retrieve this value initially during the creation
  1937.             of the object and maintain it during its lifespan.
  1938.             This means you do not need to worry about checking
  1939.             the state of the object, the user interface layout
  1940.             engine will do it for you.
  1941.  
  1942.         LA_STRPTR (STRPTR) - Pointer to the variable that holds
  1943.             the "current value" of the object. The layout engine
  1944.             will retrieve this value initially during the creation
  1945.             of the object and maintain it during its lifespan.
  1946.             This means you do not need to worry about checking
  1947.             the state of the object, the user interface layout
  1948.             engine will do it for you.
  1949.  
  1950.         LA_FRACTION (FRACTION *) - Pointer to the variable that holds
  1951.             the "current value" of the object. The layout engine
  1952.             will retrieve this value initially during the creation
  1953.             of the object and maintain it during its lifespan.
  1954.             This means you do not need to worry about checking
  1955.             the state of the object, the user interface layout
  1956.             engine will do it for you.
  1957.  
  1958.  
  1959.         TEXT_KIND:
  1960.  
  1961.             LATX_Picker (BOOL) - Attach a `select' button to the
  1962.                 right hand side of the text display.
  1963.                 Default: FALSE
  1964.  
  1965.             LATX_LockSize (BOOL) - After doing the initial layout
  1966.                 for this object, do not adapt its size again during
  1967.                 subsequent layouts. This is particularly useful if
  1968.                 you have a TEXT_KIND object in a paged group
  1969.                 and update its contents later. You need
  1970.                 to specify an object width using LA_Chars, otherwise
  1971.                 the layout engine may make it not wide enough to
  1972.                 display any text. (V15)
  1973.  
  1974.  
  1975.         VERTICAL_KIND (group to align objects vertically):
  1976.         HORIZONTAL_KIND (group to align objects horizontally):
  1977.  
  1978.             LAGR_Spread (BOOL) - Place all objects in this
  1979.                 group with roughly the same amount of space
  1980.                 between them.
  1981.                 Default: FALSE
  1982.  
  1983.             LAGR_SameSize (BOOL) - Make all objects in this
  1984.                 group the same size (for vertical groups:
  1985.                 the same height, for horizontal groups:
  1986.                 the same width).
  1987.                 Default: FALSE
  1988.  
  1989.             LAGR_LastAttributes (BOOL) - Try to copy the
  1990.                 size of the previous group for this new
  1991.                 group. May not work if this group turns
  1992.                 out to be larger than the previous group.
  1993.                 Default: FALSE
  1994.  
  1995.             LAGR_ActivePage (LONG) - Organize all child
  1996.                 groups as pages which can be flipped through
  1997.                 using LT_SetAttributes(). You need to
  1998.                 specify the number of the first page to
  1999.                 display, starting from 0.
  2000.  
  2001.                     NOTE: Specifying this tag actually enables
  2002.                         the paging feature. If you omit this
  2003.                         tag calls to flip to a specific
  2004.                         page will fail.
  2005.  
  2006.                 Default: No paging
  2007.  
  2008.             LAGR_Frame (BOOL) - Draw a recessed frame around
  2009.                 this group, even if there is no group label. (V7)
  2010.  
  2011.             LAGR_IndentX (BOOL) - Add extra horizontal indentation
  2012.                 for this group. (V10)
  2013.  
  2014.             LAGR_IndentY (BOOL) - Add extra vertical indentation
  2015.                 for this group. (V10)
  2016.  
  2017.             LAGR_NoIndent (BOOL) - Inhibit automatic size adjustion
  2018.                 and centring of this group if it is smaller than
  2019.                 the neighbouring groups. (V21)
  2020.  
  2021.             LAGR_SameWidth (WORD) - During the final layout pass,
  2022.                 make this group the same width as the group which
  2023.                 uses the given ID. Not implemented yet. (V25)
  2024.  
  2025.             LAGR_SameHeight (WORD) - During the final layout pass,
  2026.                 make this group the same height as the group which
  2027.                 uses the given ID. Not implemented yet. (V25)
  2028.  
  2029.  
  2030.         FRAME_KIND (fixed size general purpose display,
  2031.             you may render into it):
  2032.  
  2033.             LAFR_InnerWidth (LONG) - Inner width of the
  2034.                 display box.
  2035.  
  2036.             LAFR_InnerHeight (LONG) - Inner height of the
  2037.                 display box.
  2038.  
  2039.             LAFR_DrawBox (BOOL) - Draw a recessed bevel box
  2040.                 around the display box.
  2041.                 Default: FALSE
  2042.  
  2043.             LAFR_RefreshHook (struct Hook *) - Hook to call
  2044.                 when refreshing/redrawing this object. See
  2045.                 gtlayout.h for more information. (V9)
  2046.  
  2047.             LAFR_GenerateEvents (BOOL) - If TRUE, clicking
  2048.                 inside the FRAME_KIND object will generate
  2049.                 IDCMP_GADGETUP/IDCMP_GADGETDOWN events. If
  2050.                 you wish to know where the click occured,
  2051.                 make a copy of the Window->MouseX/Y entries
  2052.                 before you call LT_HandleInput()/LT_GetIMsg(). (V28)
  2053.                 Default: FALSE
  2054.  
  2055.  
  2056.         XBAR_KIND (horizontal separator bar):
  2057.  
  2058.             LAXB_FullSize (BOOL) - Make this separator bar span
  2059.                 the entire window width.
  2060.  
  2061.         BLANK_KIND (transparent placeholder):
  2062.  
  2063.             No tags are defined for this type of object (V36).
  2064.  
  2065.         BOX_KIND (multiline text display):
  2066.  
  2067.             LABX_Labels (STRPTR *) - The label texts to display
  2068.                 on the right hand side of the box. Terminate
  2069.                 this array with NULL.
  2070.  
  2071.             LABX_Lines (STRPTR *) - The text to display in the
  2072.                 box. Terminate this array with NULL.
  2073.  
  2074.             LABX_Rows (LONG) - The width of this object in
  2075.                 characters. The layout routine will try to make
  2076.                 sure that the given number of characters will
  2077.                 fit into a single line of text in this box.
  2078.                 This may be a problem with proportional spaced
  2079.                 fonts.
  2080.  
  2081.             LABX_AlignText (LONG) - Controls how text is aligned
  2082.                 in box lines:
  2083.  
  2084.                     ALIGNTEXT_LEFT - Align text to the left edge
  2085.                     ALIGNTEXT_CENTERED - Centre the text
  2086.                     ALIGNTEXT_RIGHT - Align text to the right edge
  2087.                     ALIGNTEXT_PAD - Pad text lines
  2088.  
  2089.                 Default: ALIGNTEXT_LEFT
  2090.  
  2091.             LABX_DrawBox (BOOL) - Draw a recessed bevel box
  2092.                 around the text box.
  2093.                 Default: FALSE
  2094.  
  2095.             LABX_FirstLabel (LONG) - Locale string ID of the first
  2096.                 text to use as a box label. Works in conjunction
  2097.                 with LABX_LastLabel.
  2098.  
  2099.             LABX_LastLabel (LONG) - Locale string ID of the last
  2100.                 text to use as a box label. Works in conjunction
  2101.                 with LABX_FirstLabel. When building the interface the
  2102.                 code will loop from FirstLabel..LastLabel, look
  2103.                 up the corresponding locale strings and use the
  2104.                 data to make up the label text to appear at the
  2105.                 right hand side of the box.
  2106.  
  2107.             LABX_LabelTable (LONG *) - Pointer to an array of IDs
  2108.                 to use for building the box labels. This requires
  2109.                 that a locale hook is provided with the layout handle.
  2110.                 The array is terminated by -1.
  2111.  
  2112.             LABX_ReserveSpace (BOOL) - Allocate extra memory to hold
  2113.                 the contents of the lines displayed. This avoids nasty
  2114.                 side-effects when refreshing this object.
  2115.                 Default: FALSE
  2116.  
  2117.             LABX_FirstLine (LONG) - Locale string ID of the first
  2118.                 text to print inside the box. Works in conjunction
  2119.                 with LABX_LastLine. (V26)
  2120.  
  2121.             LABX_LastLine (LONG) - Locale string ID of the last
  2122.                 text to print inside the box. Works in conjunction
  2123.                 with LABX_FirstLine. (V26)
  2124.  
  2125.             LABX_LineTable (LONG *) - Pointer to an array of IDs
  2126.                 to use for building the box contents lines. This requires
  2127.                 that a locale hook is provided with the layout handle.
  2128.                 The array is terminated by -1. (V28)
  2129.  
  2130.             LABX_Line (STRPTR) - Line to display in the box, may
  2131.                 contain '\n' line break characters, the layout engine
  2132.                 will chop the single line into single consecutive lines
  2133.                 following the '\n' chars. (V31)
  2134.  
  2135.             LABX_LineID (LONG) - Locale ID of line text to display in the
  2136.                 box, may contain '\n' line break characters, the layout
  2137.                 engine will chop the single line into single consecutive lines
  2138.                 following the '\n' chars. (V31)
  2139.  
  2140.         SLIDER_KIND:
  2141.  
  2142.             LASL_FullCheck: TRUE will cause the code to rattle
  2143.                 through all possible slider settings, starting
  2144.                 from the minimum value, ending at the maximum value.
  2145.                 While this may be a good idea for a display
  2146.                 function to map slider levels to text strings
  2147.                 of varying length it might be a problem when
  2148.                 it comes to display a range of numbers from
  2149.                 1 to 40,000: the code will loop through
  2150.                 40,000 iterations trying to find the longest
  2151.                 string.
  2152.  
  2153.                 FALSE will cause the code to calculate the
  2154.                 longest level string based only on the
  2155.                 minimum and the maximum value to check.
  2156.                 While this is certainly a good a idea when
  2157.                 it comes to display a range of numbers from
  2158.                 1 to 40,000 as only two values will be
  2159.                 checked the code may fail to produce
  2160.                 accurate results for sliders using display
  2161.                 functions mapping slider levels to strings.
  2162.  
  2163.                 Default: TRUE
  2164.  
  2165.  
  2166.         LEVEL_KIND:
  2167.  
  2168.             All tags are supported which SLIDER_KIND supports.
  2169.             The gadget level display however, can only be aligned
  2170.             to the left border.
  2171.  
  2172.  
  2173.         LISTVIEW_KIND:
  2174.  
  2175.             LALV_ExtraLabels (STRPTR *) - Place extra line
  2176.                 labels at the right of the box. Terminate
  2177.                 this array with NULL.
  2178.  
  2179.             LALV_Labels (STRPTR *) - The labels to display
  2180.                 inside the box, you can pass this array of
  2181.                 strings in rather than passing an initialized
  2182.                 List of text via GTLV_Labels. Terminate
  2183.                 this array with NULL.
  2184.  
  2185.             LALV_CursorKey (BOOL) - Let the user operate this
  2186.                 listview using the cursor keys.
  2187.  
  2188.                     NOTE: there can be only one single listview
  2189.                         per window to sport this feature.
  2190.  
  2191.                 Default: FALSE
  2192.  
  2193.             LALV_Lines (LONG) - The number of text lines this
  2194.                 listview is to display.
  2195.  
  2196.             LALV_Link (LONG) - The Gadget ID of a string gadget
  2197.                 to attach to this listview.
  2198.  
  2199.                     NOTE: you need to
  2200.                         add the Gadget in question before you add the
  2201.                         listview to refer to it or the layout routine
  2202.                         will get confused.
  2203.  
  2204.                 Passing the value NIL_LINK will create a listview
  2205.                 which displays the currently selected item, otherwise
  2206.                 you will get a read-only list.
  2207.  
  2208.             LALV_FirstLabel (LONG) - Locale string ID of the first
  2209.                 text to use as a list label. Works in conjunction
  2210.                 with LALV_LastLabel.
  2211.  
  2212.             LALV_LastLabel (LONG) - Locale string ID of the last
  2213.                 text to use as a list label. Works in conjunction
  2214.                 with LALV_FirstLabel. When building the interface the
  2215.                 code will loop from FirstLabel..LastLabel, look
  2216.                 up the corresponding locale strings and use the
  2217.                 data to make up the label text to appear in the
  2218.                 list.
  2219.  
  2220.             LALV_LabelTable (LONG *) - Pointer to an array of IDs
  2221.                 to use for building the listview contents. This requires
  2222.                 that a locale hook is provided with the layout handle.
  2223.                 The array is terminated by -1.
  2224.  
  2225.             LALV_MaxGrowX (LONG) - Maximum width of this object
  2226.                 measured in characters. When the first layout pass
  2227.                 is finished and there is still enough space left
  2228.                 to make the listview wider, the width is increased
  2229.                 until it hits the limit specified using this tag.
  2230.  
  2231.                     NOTE: there can be only one single listview
  2232.                         per window to sport this feature.
  2233.  
  2234.                 Default: 0
  2235.  
  2236.             LALV_MaxGrowY (LONG) - Maximum height of this object
  2237.                 measured in lines. When the first layout pass is
  2238.                 finished and there is still enough space left to
  2239.                 make the listview higher, the height is increased
  2240.                 until it hits the limit specified using this tag.
  2241.  
  2242.                     NOTE: there can be only one single listview
  2243.                         per window to sport this feature.
  2244.  
  2245.                 Default: 0
  2246.  
  2247.             LALV_ResizeX (BOOL) - Makes this listview resizable
  2248.                 in the horizontal direction, attaches a sizing
  2249.                 gadget to the window to open and handles window
  2250.                 resize operations automatically. (V9)
  2251.  
  2252.                     NOTE: there can be only one single listview
  2253.                         per window to sport this feature.
  2254.  
  2255.                         Also listen to IDCMP_CLOSEWINDOW events
  2256.                         which may be generated if the layout
  2257.                         engine runs out of memory when rebuilding
  2258.                         the user interface.
  2259.  
  2260.                 Default: FALSE
  2261.  
  2262.             LALV_ResizeY (BOOL) - Makes this listview resizable
  2263.                 in the vertical direction, attaches a sizing
  2264.                 gadget to the window to open and handles window
  2265.                 resize operations automatically. (V9)
  2266.  
  2267.                     NOTE: there can be only one single listview
  2268.                         per window to sport this feature.
  2269.  
  2270.                         Also listen to IDCMP_CLOSEWINDOW events
  2271.                         which may be generated if the layout
  2272.                         engine runs out of memory when rebuilding
  2273.                         the user interface.
  2274.  
  2275.                 Default: FALSE
  2276.  
  2277.             LALV_MinChars (WORD) - Minimum width for this
  2278.                 object, measured in characters. Used in
  2279.                 conjunction with LALV_ResizeX. (V9)
  2280.  
  2281.             LALV_MinLines (WORD) - Minimum height for this
  2282.                 object, measured in lines. Used in
  2283.                 conjunction with LALV_ResizeY. (V9)
  2284.  
  2285.             LALV_LockSize (BOOL) - After doing the initial layout
  2286.                 for this object, do not adapt its size again during
  2287.                 subsequent layouts. This is particularly useful if
  2288.                 you have a LISTVIEW_KIND object in a paged group
  2289.                 and keep adding new entries to the list. You need
  2290.                 to specify an object width using LA_Chars, otherwise
  2291.                 the layout engine may make it not wide enough to
  2292.                 display any entries. (V8)
  2293.  
  2294.             LALV_FlushLabelLeft (BOOL) - For a gadget label placed
  2295.                 above the listview align the text to the left edge
  2296.                 of the view. (V9)
  2297.  
  2298.             LALV_TextAttr (struct TextAttr *) - You can specify a
  2299.                 fixed-width font to be used for the list display.
  2300.                 The TextAttr (or TTextAttr) you provide must be ready
  2301.                 to go so the layout code can open the font later.
  2302.  
  2303.                 To get the current system default font, which is
  2304.                 guaranteed to be fixed-width, pass ~0 instead of a
  2305.                 pointer to a TextAttr structure. (V10)
  2306.  
  2307.                     NOTE: The font *MUST* be fixed-width or the layout
  2308.                         will fail.
  2309.  
  2310.                          Choose your font in such a way that it matches
  2311.                          in width and height with the other probably
  2312.                          proportional-spaced user interface font.
  2313.  
  2314.                          If the layout engine decides to step down in
  2315.                          font size, all LISTVIEW_KIND objects which were
  2316.                          configured to use a special fixed-width font
  2317.                          will `forget' about it. This won't matter much
  2318.                          as the fonts the engine chooses will always be
  2319.                          fixed-width anyway.
  2320.  
  2321.             LALV_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2322.                 which will be set to the gadget's current setting.
  2323.                 If this tag is set, you will hear no events from this
  2324.                 object any more. (V23)
  2325.  
  2326.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2327.                         which may be generated if the layout
  2328.                         engine runs out of memory when rebuilding
  2329.                         the user interface.
  2330.  
  2331.             LALV_Selected (LONG) - In this context, this tag is an
  2332.                 alias for GTLV_Selected. See
  2333.                 gtlayout.library/LT_SetAttributes for more information
  2334.                 on how the meaning of this tag differs from this (V34).
  2335.  
  2336.         INTEGER_KIND:
  2337.  
  2338.             LAIN_LastGadget (BOOL) - Pressing return with this
  2339.                 gadget active will stop activating the next
  2340.                 following string gadget type if TRUE is passed.
  2341.                 Default: FALSE
  2342.  
  2343.             LAIN_Min (LONG) - Minimum accepted numeric value.
  2344.                 Default: -2147483647
  2345.  
  2346.             LAIN_Max (LONG) - Maximum accepted numeric value.
  2347.                 Default:  2147483647
  2348.  
  2349.             LAIN_UseIncrementers (BOOL) - Use TRUE to add incrementer
  2350.                 arrow buttons to the right of the numeric entry field.
  2351.                 These buttons will let you cycle through a set of
  2352.                 numbers to be displayed in the numeric entry field.
  2353.                 Default: FALSE
  2354.  
  2355.             LAIN_HistoryLines (LONG) - Number of numbers entered to
  2356.                 keep as a backlog.
  2357.                 Default: 0
  2358.  
  2359.             LAIN_HistoryHook (struct Hook *) - Hook code to call when
  2360.                 entering a number into the backlog. See gtlayout.h for
  2361.                 more information.
  2362.                 Default: NULL
  2363.  
  2364.             LAIN_IncrementerHook (struct Hook *) - Hook code to call
  2365.                 when cycling through numeric values. See gtlayout.h for
  2366.                 more information.
  2367.                 Default: NULL
  2368.  
  2369.             LAIN_Activate (BOOL) - When the window opens, make this
  2370.                 gadget the active one. (V21)
  2371.  
  2372.                     NOTE: There can be only one gadget of this type
  2373.                         per window.
  2374.  
  2375.                 Default: FALSE
  2376.  
  2377.  
  2378.         STRING_KIND:
  2379.  
  2380.             LAST_LastGadget (BOOL) - Pressing return with this
  2381.                 gadget active will stop activating the next
  2382.                 following string gadget type if TRUE is passed.
  2383.                 Default: FALSE
  2384.  
  2385.             LAST_Link (LONG) - Gadget ID of the listview to attach
  2386.                 this string gadget to.
  2387.  
  2388.                     NOTE: you need to add the string gadget before
  2389.                         you add the listview to refer to it or the
  2390.                         layout routine will get confused.
  2391.  
  2392.             LAST_Picker (BOOL) - Attach a `select' button to the
  2393.                 right hand side of the string gadget.
  2394.                 Default: FALSE
  2395.  
  2396.             LAST_HistoryLines (LONG) - Number of lines to keep as
  2397.                 a backlog.
  2398.                 Default: 0
  2399.  
  2400.             LAST_HistoryHook (struct Hook *) - Hook code to call
  2401.                 when entering a line into the backlog. See gtlayout.h
  2402.                 for more information.
  2403.                 Default: NULL
  2404.  
  2405.             LAST_Activate (BOOL) - When the window opens, make this
  2406.                 gadget the active one. (V21)
  2407.  
  2408.                     NOTE: There can be only one gadget of this type
  2409.                         per window.
  2410.  
  2411.                 Default: FALSE
  2412.  
  2413.         PASSWORD_KIND (string gadget type which does not
  2414.             display its contents):
  2415.  
  2416.             LAPW_LastGadget (BOOL) - Pressing return with this
  2417.                 gadget active will stop activating the next
  2418.                 following string gadget type if TRUE is passed.
  2419.                 Default: FALSE
  2420.  
  2421.             LAPW_HistoryLines (LONG) - Number of lines to keep as
  2422.                 a backlog.
  2423.                 Default: 0
  2424.  
  2425.             LAPW_HistoryHook (struct Hook *) - Hook code to call
  2426.                 when entering a line into the backlog. See gtlayout.h
  2427.                 for more information.
  2428.                 Default: NULL
  2429.  
  2430.             LAPW_Activate (BOOL) - When the window opens, make this
  2431.                 gadget the active one. (V21)
  2432.  
  2433.                     NOTE: There can be only one gadget of this type
  2434.                         per window.
  2435.  
  2436.                 Default: FALSE
  2437.  
  2438.             This object type accepts all the GTST_#? tag items.
  2439.  
  2440.  
  2441.         PALETTE_KIND:
  2442.  
  2443.             LAPA_SmallPalette (BOOL) - Make the palette display
  2444.                 a bit smaller than usual.
  2445.                 Default: FALSE
  2446.  
  2447.             LAPA_Lines (LONG) - Number of lines the palette
  2448.                 display should cover.
  2449.                 Default: No preference
  2450.  
  2451.             LAPA_UsePicker (BOOL) - This tag effectively changes the
  2452.                 gadget type. Instead of a list of colours to pick from
  2453.                 the user will see a rectangle filled in the selected
  2454.                 colour with a picker button next to it. This gadget
  2455.                 will generate IDCMP_IDCMPUPDATE events when the picker
  2456.                 button is pressed. (V10)
  2457.  
  2458.  
  2459.         BUTTON_KIND:
  2460.  
  2461.             LA_Label (STRPTR)
  2462.             LA_LabelID (LONG) - These two define the button label, i.e.
  2463.                 the text that is printed within the button box. Optionally,
  2464.                 this text may include newline characters ("\n") which will
  2465.                 cause the button text to be broken into several lines.
  2466.                 This particular feature requires gtlayout.library v12 or
  2467.                 higher. Single line label have always been supported.
  2468.  
  2469.             LABT_ReturnKey (BOOL) - Let the user operate this
  2470.                 button by pressing the return key, making it the
  2471.                 so-called default button, or default choice. The
  2472.                 button select box will appear slightly bolder than
  2473.                 normal buttons are.
  2474.  
  2475.                     NOTE: there can be only one single button per
  2476.                         window to sport this feature.
  2477.  
  2478.                 Default: FALSE
  2479.  
  2480.             LABT_EscKey (BOOL) - Let the user operate this
  2481.                 button by pressing the Escape key.
  2482.  
  2483.                     NOTE: there can be only one single button per
  2484.                         window to use this feature.
  2485.  
  2486.                 Default: FALSE
  2487.  
  2488.             LABT_ExtraFat (BOOL) - Make this button a bit
  2489.                 larger than usual.
  2490.                 Default: FALSE
  2491.  
  2492.             LABT_Lines (STRPTR *) - Use the given string array
  2493.                 to create a multiline gadget label. Terminate the
  2494.                 array with a NULL. (V12)
  2495.  
  2496.             LABT_FirstLine (LONG) - Locale ID of first label line. (V12)
  2497.  
  2498.             LABT_LastLine (LONG) - Locale ID of last label line. (V12)
  2499.  
  2500.             LABT_DefaultCorrection (BOOL) - Make the button slightly
  2501.                 wider and taller so its size matches the default
  2502.                 button. (V21)
  2503.  
  2504.             LABT_Smaller (BOOL) - Make this button a little smaller
  2505.                 than usual. (V21)
  2506.  
  2507.         GAUGE_KIND (general purpose progress report display):
  2508.  
  2509.             LAGA_Percent (LONG) - Indicator position, can range
  2510.                 from 0..100.
  2511.                 Default: 0
  2512.  
  2513.             LAGA_InfoLength (LONG) - Maximum number of characters
  2514.                 to reserve for text printed in the gauge display.
  2515.                 Default: 0
  2516.  
  2517.             LAGA_InfoText (STRPTR) - Text to print in the gauge
  2518.                 display.
  2519.  
  2520.             LAGA_Tenth (BOOL) - Instead of a continuously growing
  2521.                 bar you will get a set of exactly ten blocks,
  2522.                 each separated by a hairline. (V19)
  2523.                 Default: FALSE
  2524.  
  2525.                LAGA_NoTicks (BOOL) - If TRUE suppresses drawing the
  2526.                    ticks below the gauge box.
  2527.                    Default: FALSE
  2528.  
  2529.         CYCLE_KIND:
  2530.  
  2531.             LACY_FirstLabel (LONG) - Locale string ID of the first
  2532.                 text to use as a label. Works in conjunction
  2533.                 with LACY_LastLabel.
  2534.  
  2535.             LACY_LastLabel (LONG) - Locale string ID of the last
  2536.                 text to use as a label. Works in conjunction
  2537.                 with LACY_FirstLabel. When building the interface the
  2538.                 code will loop from FirstLabel..LastLabel, look
  2539.                 up the corresponding locale strings and use the
  2540.                 data to make up the label text.
  2541.  
  2542.             LACY_LabelTable (LONG *) - Pointer to an array of IDs
  2543.                 to use for building the cycle labels. This requires
  2544.                 that a locale hook is provided with the layout handle.
  2545.                 The array is terminated by -1.
  2546.  
  2547.             LACY_TabKey (BOOL) - Connect this object to the tabulator
  2548.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2549.                 to cycle to the previous entry. (V9)
  2550.  
  2551.                     NOTE: there can be only one single button per
  2552.                         window to use this feature.
  2553.  
  2554.                 Default: FALSE
  2555.  
  2556.             LACY_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2557.                 which will be set to the gadget's current setting.
  2558.                 If this tag is set, you will hear no events from this
  2559.                 object any more. (V7)
  2560.  
  2561.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2562.                         which may be generated if the layout
  2563.                         engine runs out of memory when rebuilding
  2564.                         the user interface.
  2565.  
  2566.  
  2567.         POPUP_KIND:
  2568.  
  2569.             (This features requires gtlayout.library v22 or higher
  2570.              and Kickstart 3.0 or higher).
  2571.  
  2572.             LAPU_FirstLabel (LONG) - Locale string ID of the first
  2573.                 text to use as a label. Works in conjunction
  2574.                 with LAPU_LastLabel.
  2575.  
  2576.             LAPU_LastLabel (LONG) - Locale string ID of the last
  2577.                 text to use as a label. Works in conjunction
  2578.                 with LAPU_FirstLabel. When building the interface the
  2579.                 code will loop from FirstLabel..LastLabel, look
  2580.                 up the corresponding locale strings and use the
  2581.                 data to make up the label text.
  2582.  
  2583.             LAPU_LabelTable (LONG *) - Pointer to an array of IDs
  2584.                 to use for building the cycle labels. This requires
  2585.                 that a locale hook is provided with the layout handle.
  2586.                 The array is terminated by -1.
  2587.  
  2588.             LAPU_TabKey (BOOL) - Connect this object to the tabulator
  2589.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2590.                 to cycle to the previous entry.
  2591.  
  2592.                     NOTE: there can be only one single button per
  2593.                         window to use this feature.
  2594.  
  2595.                 Default: FALSE
  2596.  
  2597.             LAPU_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2598.                 which will be set to the gadget's current setting.
  2599.                 If this tag is set, you will hear no events from this
  2600.                 object any more.
  2601.  
  2602.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2603.                         which may be generated if the layout
  2604.                         engine runs out of memory when rebuilding
  2605.                         the user interface.
  2606.  
  2607.             LAPU_CentreActive (BOOL) - If TRUE, the popup menu will
  2608.                 appear with the currently active entry centred below
  2609.                 the mouse pointer. (V31)
  2610.  
  2611.         TAB_KIND:
  2612.  
  2613.             (This features requires gtlayout.library v24 or higher)
  2614.  
  2615.             LATB_FirstLabel (LONG) - Locale string ID of the first
  2616.                 text to use as a label. Works in conjunction
  2617.                 with LATB_LastLabel.
  2618.  
  2619.             LATB_LastLabel (LONG) - Locale string ID of the last
  2620.                 text to use as a label. Works in conjunction
  2621.                 with LATB_FirstLabel. When building the interface the
  2622.                 code will loop from FirstLabel..LastLabel, look
  2623.                 up the corresponding locale strings and use the
  2624.                 data to make up the label text.
  2625.  
  2626.             LATB_LabelTable (LONG *) - Pointer to an array of IDs
  2627.                 to use for building the cycle labels. This requires
  2628.                 that a locale hook is provided with the layout handle.
  2629.                 The array is terminated by -1.
  2630.  
  2631.             LATB_TabKey (BOOL) - Connect this object to the tabulator
  2632.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2633.                 to cycle to the previous entry.
  2634.  
  2635.                     NOTE: there can be only one single button per
  2636.                         window to use this feature.
  2637.  
  2638.                 Default: FALSE
  2639.  
  2640.             LATB_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2641.                 which will be set to the gadget's current setting.
  2642.                 If this tag is set, you will hear no events from this
  2643.                 object any more.
  2644.  
  2645.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2646.                         which may be generated if the layout
  2647.                         engine runs out of memory when rebuilding
  2648.                         the user interface.
  2649.  
  2650.             LATB_FullSize (BOOL) - By default a TAB_KIND object
  2651.                 covers the entire width of the group it sits in.
  2652.                 With LATB_FullSize set to true it will cover the
  2653.                 width of the entire Window.
  2654.  
  2655.                 Default: FALSE
  2656.  
  2657.  
  2658.         MX_KIND:
  2659.  
  2660.             LAMX_FirstLabel (LONG) - Locale string ID of the first
  2661.                 text to use as a label. Works in conjunction
  2662.                 with LAMX_LastLabel.
  2663.  
  2664.             LAMX_LastLabel (LONG) - Locale string ID of the last
  2665.                 text to use as a label. Works in conjunction
  2666.                 with LAMX_FirstLabel. When building the interface the
  2667.                 code will loop from FirstLabel..LastLabel, look
  2668.                 up the corresponding locale strings and use the
  2669.                 data to make up the label text.
  2670.  
  2671.             LAMX_LabelTable (LONG *) - Pointer to an array of IDs
  2672.                 to use for building the radio labels. This requires
  2673.                 that a locale hook is provided with the layout handle.
  2674.                 The array is terminated by -1.
  2675.  
  2676.             LAMX_TabKey (BOOL) - Connect this object to the tabulator
  2677.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2678.                 to cycle to the previous entry. (V9)
  2679.  
  2680.                     NOTE: there can be only one single button per
  2681.                         window to use this feature.
  2682.  
  2683.                 Default: FALSE
  2684.  
  2685.             LAMX_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2686.                 which will be set to the gadget's current setting.
  2687.                 If this tag is set, you will hear no events from this
  2688.                 object any more. (V7)
  2689.  
  2690.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2691.                         which may be generated if the layout
  2692.                         engine runs out of memory when rebuilding
  2693.                         the user interface.
  2694.  
  2695.  
  2696.         SCROLLER_KIND:
  2697.  
  2698.             LASC_Thin (BOOL) - Make the scroller a bit thinner
  2699.                 than usual.
  2700.                 Default: FALSE
  2701.  
  2702.             GA_RelVerify (BOOL) - Hear every IDCMP_GADGETUP
  2703.                 event from scroller.
  2704.                 Default: TRUE
  2705.  
  2706.                         NOTE: This is different from what
  2707.                          gadtools.library uses.
  2708.  
  2709.             GA_Immediate (BOOL) - Hear every IDCMP_GADGETDOWN
  2710.                 event from scroller
  2711.                 Default: TRUE
  2712.  
  2713.                         NOTE: This is different from what
  2714.                          gadtools.library uses.
  2715.  
  2716.         TAPEDECK_KIND:
  2717.  
  2718.             LATD_ButtonType (LONG) - Select the image to display
  2719.                 in the button, must be one of the following:
  2720.  
  2721.                     TDBT_BACKWARD
  2722.                         "<<" Symbol
  2723.  
  2724.                     TDBT_FORWARD
  2725.                         ">>" Symbol
  2726.  
  2727.                     TDBT_PREVIOUS
  2728.                         "|<" Symbol
  2729.  
  2730.                     TDBT_NEXT
  2731.                         ">|" Symbol
  2732.  
  2733.                     TDBT_STOP
  2734.                         Stop symbol (filled square)
  2735.  
  2736.                     TDBT_PAUSE
  2737.                         "||" pause symbol (broken square)
  2738.  
  2739.                     TDBT_RECORD
  2740.                         Record symbol (filled circle)
  2741.  
  2742.                     TDBT_REWIND
  2743.                         "<" symbol
  2744.  
  2745.                     TDBT_EJECT
  2746.                         Eject symbol (broken upward pointing arrow)
  2747.  
  2748.                     TDBT_PLAY
  2749.                         ">" symbol
  2750.  
  2751.             LATD_Toggle (BOOL) - Make this object a toggle-select
  2752.                 button.
  2753.                 Default: FALSE
  2754.  
  2755.             LATD_Pressed (BOOL) - Make this button appear to be
  2756.                 pressed.
  2757.  
  2758.                     NOTE: requires "LATD_Toggle,TRUE" attribute.
  2759.  
  2760.                 Default: FALSE
  2761.  
  2762.             LATD_Smaller (BOOL) - Make this button a bit smaller
  2763.                 than usual.
  2764.                 Default: FALSE
  2765.  
  2766.             LATD_Tick (BOOL) - Hear IDCMP_GADGETUP events while the
  2767.                 buttons is being pressed; the IntuiMessage->Code entry
  2768.                 will be 0 while the button is being pressed, and
  2769.                 will be 1 as soon as the button is released. (V12)
  2770.  
  2771.                 Default: FALSE
  2772.  
  2773.  
  2774.         BOOPSI_KIND:
  2775.  
  2776.             (requires gtlayout.library v10 or higher)
  2777.  
  2778.             LABO_TagCurrent (Tag) - The Tag ID that represents the
  2779.                 current object value. For PROPGCLASS this would be
  2780.                 PGA_Top.
  2781.  
  2782.             LABO_TagTextAttr (Tag) - The Tag ID that represents the
  2783.                 TextAttr value the object expects. For gadgets this
  2784.                 would be GA_TextAttr.
  2785.  
  2786.             LABO_TagDrawInfo (Tag) - The Tag ID that represents the
  2787.                 DrawInfo value the object expects.
  2788.  
  2789.             LABO_TagLink (Tag) - The Tag ID that represents a pointer
  2790.                 to a different object the object expects. For the
  2791.                 colorwheel.gadget this would be WHEEL_GradientSlider.
  2792.  
  2793.             LABO_TagScreen (Tag) - The Tag ID that represents the
  2794.                 screen the object expects. For the colorwheel.gadget
  2795.                 this would be WHEEL_Screen.
  2796.  
  2797.             LABO_Link (LONG) - The ID of the object this object should
  2798.                 be linked to. This will be resolved later when gadgets
  2799.                 are created.
  2800.  
  2801.                     NOTE: Forward references are not resolved, only
  2802.                         backward references are allowed. This means that
  2803.                         if you wish to link object A to object B,
  2804.                         object A must be created before object B
  2805.                         is created.
  2806.  
  2807.             LABO_ClassInstance (Class *) - This is the first parameter
  2808.                 you would pass to NewObjectA().
  2809.  
  2810.                     NOTE: Only classes derived from gadgetclass and
  2811.                       gadgetclass itself may be used.
  2812.  
  2813.             LABO_ClassName (STRPTR) - This is the second parameter you would
  2814.                 pass to NewObject().
  2815.  
  2816.                     NOTE: Only classes derived from gadgetclass and
  2817.                         gadgetclass itself may be used.
  2818.  
  2819.             LABO_ClassLibraryName (STRPTR) - This tag is particularly useful
  2820.                 for gadget class implementations wrapped into libraries, such as
  2821.                 colorwheel.gadget. When opened, they make the classes they
  2822.                 represent publicly available so subsequent calls to
  2823.                 NewObject(NULL,<Classname>,...) can be made. The
  2824.                 LABO_ClassLibraryName tag will cause gtlayout.library to open
  2825.                 the class library before any calls to NewObject() are made.
  2826.  
  2827.                     NOTE: Only classes derived from gadgetclass and
  2828.                         gadgetclass itself may be used.
  2829.  
  2830.                         The LABO_ClassLibraryName tag requires that you
  2831.                         specify the class name with the LABO_ClassName. It is
  2832.                         not enough to just use the LABO_ClassLibraryName tag.
  2833.  
  2834.             LABO_ExactWidth (WORD) - This is the exact width of the object to
  2835.                 use. This effectively overrides whatever you specified using
  2836.                 the LA_Chars tag and keeps gtlayout.library from shrinking and
  2837.                 expanding the object as needed.
  2838.  
  2839.             LABO_ExactHeight (WORD) - This is the exact height of the object to
  2840.                 use. This effectively overrides whatever you specified using
  2841.                 the LA_Lines tag and keeps gtlayout.library from shrinking and
  2842.                 expanding the object as needed.
  2843.  
  2844.             LABO_RelFontHeight (WORD) - This tag affects the height of the
  2845.                 object; when specified, it is derived from the user interface
  2846.                 font height plus the value given with LABO_RelFontHeight.
  2847.  
  2848.             LABO_FullWidth (BOOL) - Use this tag if you wish the object to
  2849.                 cover the entire width of the group it resides within.
  2850.  
  2851.             LABO_FullHeight (BOOL) - Use this tag if you wish the object to
  2852.                 cover the entire height of the group it resides within.
  2853.  
  2854.             LABO_ActivateHook (struct Hook *) - Hook to invoke when the
  2855.                 layout engine decides that this particular object should
  2856.                 be activated. The hook is called with the following
  2857.                 parameters:
  2858.  
  2859.                 Success = ActivateFunc(struct Hook *Hook,LayoutHandle *Handle,
  2860.                   D0                                 A0                  A2
  2861.  
  2862.                              Object *object)
  2863.                                        A1
  2864.  
  2865.                 The object pointer actually refers to the instance of the
  2866.                 BOOPSI object created. Return FALSE if your object could not
  2867.                 be activated, TRUE if it worked. If you return TRUE, no special
  2868.                 keyboard event will be generated. (V13)
  2869.  
  2870.             NOTE: All tags passed to LT_New() for BOOPSI_KIND objects are
  2871.                 passed through to NewObjectA() later. The library makes
  2872.                 a copy of the tag item list, so all data valid in the
  2873.                 scope when LT_New() is called must also be valid later
  2874.                 when LT_Build() is invoked.
  2875.  
  2876.                 The gadget label is *NOT* passed through to the object,
  2877.                 it effectively receives the label a plain gadtools object
  2878.                 would receive, similar to what happens to FRAME_KIND
  2879.                 objects and the like.
  2880.  
  2881.    RESULT
  2882.     none
  2883.  
  2884.    BUGS
  2885.     Up to v25 the SCROLLER_KIND object did not support GA_Immediate
  2886.     or GA_RelVerify. The space for the variables was there, but the
  2887.     code was missing.
  2888.  
  2889.     POPUP_KIND objects don't work well in simple refresh windows,
  2890.     as refresh events can get lost. Use a smart refresh window
  2891.     instead or call gadtools.library/LT_CatchUpRefresh() regularly.
  2892.  
  2893.    SEE ALSO
  2894.     gadtools.library/CreateGadgetA
  2895.  
  2896. gtlayout.library/LT_NewLevelWidth           gtlayout.library/LT_NewLevelWidth
  2897.  
  2898.    NAME
  2899.     LT_NewLevelWidth -- Determine the maximum width of a SLIDER_KIND
  2900.                         level string. (V14)
  2901.  
  2902.    SYNOPSIS
  2903.     Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
  2904.       D0                    A0        A1         A2     D0  D1    A3
  2905.  
  2906.                               MaxLen,FullCheck);
  2907.                                 D3      D2
  2908.  
  2909.     LONG LT_LevelWidth(LayoutHandle *,STRPTR,
  2910.                        LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
  2911.                        LONG *,BOOL);
  2912.  
  2913.    FUNCTION
  2914.     In order to make room for the level text displayed by a
  2915.     SLIDER_KIND object one needs to know how much space the
  2916.     longest level string will occupy. Otherwise, the level
  2917.     text may overwrite the gadget label text or the slider
  2918.     container. This routine will rattle through all possible
  2919.     slider settings (as given via the Min and the Max
  2920.     level values) and determine the longest label string
  2921.     according to the font used.
  2922.  
  2923.    INPUTS
  2924.     Handle - Pointer to a LayoutHandle structure, as returned by
  2925.         a call to LT_CreateHandleTags().
  2926.  
  2927.     FormatString - The sprintf() style formatting string to be used
  2928.         to format the slider level settings into text.
  2929.         This is the same string you would pass in via
  2930.         the GTSL_LevelFormat tag when creating the
  2931.         slider object.
  2932.         Default: "%lD" for systems which have locale.library
  2933.             installed, "%ld" otherwise.
  2934.  
  2935.     DispFunc - A pointer to the function to filter the slider level
  2936.         values. The result of this function will then be
  2937.         used to format a string into the slider level text.
  2938.         This is the same parameter you would pass in via
  2939.         the GTSL_DispFunc tag when creating the slider
  2940.         object.
  2941.  
  2942.         NOTE: the routine will be called with a NULL Gadget
  2943.             parameter, make sure your code will handle
  2944.             this nicely.
  2945.  
  2946.         Default: no display function
  2947.  
  2948.     Min - The smallest value the slider can be set to. This is
  2949.         same value you would pass in via GTSL_Min when creating
  2950.         the slider object.
  2951.  
  2952.     Max - The largest value the slider can be set to. This is
  2953.         same value you would pass in via GTSL_Max when creating
  2954.         the slider object.
  2955.  
  2956.     MaxWidth - Pointer to a place to store the width of the
  2957.         longest level string in pixels. If you pass
  2958.         in NULL instead of the address of a variable
  2959.         no harm will be done.
  2960.  
  2961.     MaxLen - Pointer to a place to store the length of the
  2962.         longest level string in characters. If you pass
  2963.         in NULL instead of the address of a variable
  2964.         no harm will be done.
  2965.  
  2966.     FullCheck - TRUE will cause the code to rattle through all
  2967.         possible slider settings, starting from the
  2968.         minimum value, ending at the maximum value.
  2969.         While this may be a good idea for a display
  2970.         function to map slider levels to text strings
  2971.         of varying length it might be a problem when
  2972.         it comes to display a range of numbers from
  2973.         1 to 40,000: the code will loop through
  2974.         40,000 iterations trying to find the longest
  2975.         string.
  2976.  
  2977.         FALSE will cause the code to calculate the
  2978.         longest level string based only on the
  2979.         minimum and the maximum value to check.
  2980.         While this is certainly a good a idea when
  2981.         it comes to display a range of numbers from
  2982.         1 to 40,000 as only two values will be
  2983.         checked the code may fail to produce
  2984.         accurate results for sliders using display
  2985.         functions mapping slider levels to strings.
  2986.  
  2987.    RESULT
  2988.     Index - The slider level which gives the longest
  2989.         level string.
  2990.  
  2991.    NOTES
  2992.     This function does exactly what gtlayout.library/LT_LevelWidth
  2993.     does, but uses a slightly different register ordering. Namely,
  2994.     the MaxLen pointer is passed in D3 instead of A5.
  2995.  
  2996.    SEE ALSO
  2997.     gtlayout.library/LT_LevelWidth
  2998.  
  2999. gtlayout.library/LT_NewMenuTagList         gtlayout.library/LT_NewMenuTagList
  3000.  
  3001.    NAME
  3002.     LT_NewMenuTagList -- Allocate and layout menu items (V11)
  3003.  
  3004.    SYNOPSIS
  3005.     Menu = LT_NewMenuTagList(Tags)
  3006.      D0                       A0
  3007.  
  3008.     struct Menu *LT_NewMenuTagList(struct TagItem *);
  3009.  
  3010.     struct Menu *LT_NewMenuTags(...);
  3011.  
  3012.    FUNCTION
  3013.     Allocates Menus and MenuItems similar to LT_LayoutMenus().
  3014.  
  3015.     As of v18 this routine will validate menu mutual exclusion
  3016.     information.
  3017.  
  3018.    INPUTS
  3019.     Tags - Pointer to a list of tagitem values, as found
  3020.         in gtlayout.h
  3021.  
  3022.  
  3023.     Valid tags include:
  3024.  
  3025.     LAMN_Screen (struct Screen *) - Pointer to the Screen
  3026.         the menu is to appear upon. This tag is mandatory,
  3027.         unless the LAMN_LayoutHandle tag is used.
  3028.  
  3029.     LAMN_TextAttr (struct TextAttr *) - Pointer to the
  3030.         TextAttr to use for the menu layout. If this tag
  3031.         is omitted the Screen->Font will be used.
  3032.  
  3033.     LAMN_Error (LONG *) - Pointer to variable to receive
  3034.         an error in case of failure.
  3035.  
  3036.     LAMN_AmigaGlyph (struct Image *) - Pointer to Image to
  3037.         use as the Amiga glyph in menus. Will be ignored if
  3038.         NULL.
  3039.  
  3040.         NOTE: Ignored by intuition.library v37 and below.
  3041.  
  3042.     LAMN_CheckmarkGlyph (struct Image *) - Pointer to Image to
  3043.         use as the checkmark glyph in menus. Will be ignored
  3044.         if NULL.
  3045.  
  3046.     LAMN_LayoutHandle (LayoutHandle *) - Pointer to a valid
  3047.         LayoutHandle as created by LT_CreateHandle. This tag
  3048.         provides all the information the single tags
  3049.         LAMN_Screen..LAMN_CheckmarkGlyph would otherwise
  3050.         need to provide.
  3051.  
  3052.     LAMN_TitleText (STRPTR) - Name of new menu to create.
  3053.         You may precede the name with the keyboard shortcut
  3054.         to assign to this menu item as follows:
  3055.  
  3056.            A\0Save as...
  3057.  
  3058.         This will create a menu item using the shortcut "A"
  3059.         and the title "Save as...".
  3060.  
  3061.     LAMN_TitleID (LONG) - Locale ID corresponding to the
  3062.         name of the new menu to create.
  3063.         You may precede the name with the keyboard shortcut
  3064.         to assign to this menu item as follows:
  3065.  
  3066.            A\0Save as...
  3067.  
  3068.         This will create a menu item using the shortcut "A"
  3069.         and the title "Save as...".
  3070.  
  3071.     LAMN_ItemText (STRPTR) - Name of new menu item to create.
  3072.         You may precede the name with the keyboard shortcut
  3073.         to assign to this menu item as follows:
  3074.  
  3075.            A\0Save as...
  3076.  
  3077.         This will create a menu item using the shortcut "A"
  3078.         and the title "Save as...".
  3079.  
  3080.     LAMN_ItemID (LONG) - Locale ID corresponding to the
  3081.         name of the new menu item to create.
  3082.         You may precede the name with the keyboard shortcut
  3083.         to assign to this menu item as follows:
  3084.  
  3085.            A\0Save as...
  3086.  
  3087.         This will create a menu item using the shortcut "A"
  3088.         and the title "Save as...".
  3089.  
  3090.     LAMN_SubText (STRPTR) - Name of new submenu item to create.
  3091.         You may precede the name with the keyboard shortcut
  3092.         to assign to this menu item as follows:
  3093.  
  3094.            A\0Save as...
  3095.  
  3096.         This will create a menu item using the shortcut "A"
  3097.         and the title "Save as...".
  3098.  
  3099.     LAMN_SubID (LONG) - Locale ID corresponding to the
  3100.         name of the new submenu item to create.
  3101.         You may precede the name with the keyboard shortcut
  3102.         to assign to this menu item as follows:
  3103.  
  3104.            A\0Save as...
  3105.  
  3106.         This will create a menu item using the shortcut "A"
  3107.         and the title "Save as...".
  3108.  
  3109.     LAMN_KeyText (STRPTR) - Pointer to the string whose first
  3110.         character will be used as the keyboard shortcut for
  3111.         this menu/submenu item.
  3112.  
  3113.     LAMN_KeyID (LONG) - Locale ID corresponding to the string whose
  3114.         first character will be used as the keyboard shortcut for
  3115.         this menu/submenu item.
  3116.  
  3117.     LAMN_CommandText (STRPTR) - Pointer to the string which
  3118.         will be used as the keyboard shortcut for this
  3119.         menu/submenu item.
  3120.  
  3121.     LAMN_CommandID (LONG) - Locale ID corresponding to the string
  3122.         which will be used as the keyboard shortcut for
  3123.         this menu/submenu item.
  3124.  
  3125.     LAMN_MutualExclude (ULONG) - Mutual exclusion information for
  3126.         this menu/submenu item.
  3127.  
  3128.     LAMN_UserData (APTR) - User data information for this
  3129.         menu/menu item/submenu item.
  3130.  
  3131.     LAMN_Disabled (BOOL) - Controls whether this
  3132.         menu/menu item/submenu item should be disabled.
  3133.  
  3134.     LAMN_CheckIt (BOOL) - Controls whether this menu/submenu item
  3135.         should be prepared to hold a checkmark.
  3136.  
  3137.             NOTE: This does not set the checkmark, use LAMN_Checked
  3138.                 for this purpose.
  3139.  
  3140.     LAMN_Checked (BOOL) - Controls whether this menu/submenu item
  3141.         should be marked with a checkmark. This tag implies
  3142.         "LAMN_Checked,TRUE".
  3143.  
  3144.     LAMN_Toggle (BOOL) - Controls whether this menu/submenu item
  3145.         should be prepared to hold a checkmark the user is to
  3146.         toggle on demand. This tag implies "LAMN_Checked,TRUE".
  3147.  
  3148.             NOTE: this does not set the checkmark, use LAMN_Checked
  3149.                 for this purpose.
  3150.  
  3151.     LAMN_Code (UWORD) - Raw key code to associate with this
  3152.         menu/submenu item. To find out if a rawkey event
  3153.         corresponds to this menu item use LT_FindMenuCommand.
  3154.  
  3155.     LAMN_Qualifier (ULONG) - Key qualifier to associate
  3156.         with this menu/submenu item.
  3157.  
  3158.             NOTE: the comparison does not distinguish between
  3159.                 the left and right shift/caps/alt qualifier keys.
  3160.  
  3161.     LAMN_ID (ULONG) - Unique ID to associate with this
  3162.         menu/menu item/submenu item. You can use this
  3163.         later to look up data using LT_GetMenuItem, etc.
  3164.  
  3165.     LAMN_ExtraSpace (UWORD) - Number of pixels to put between
  3166.         neighbouring menu titles. (V18)
  3167.         Default: 0 pixels.
  3168.  
  3169.    RESULT
  3170.     Menu - Pointer to Menu structure, ready to pass to
  3171.            SetMenuStrip(), NULL on failure.
  3172.  
  3173.    EXAMPLE
  3174.     The following tagitem list:
  3175.  
  3176.         LAMN_TitleText,     "Project"
  3177.          LAMN_ItemText,     "New",
  3178.           LAMN_KeyText,     "N",
  3179.          LAMN_ItemText,     "Open...",
  3180.           LAMN_KeyText,     "O",
  3181.          LAMN_ItemText,     NM_BARLABEL,
  3182.          LAMN_ItemText,     "Save",
  3183.           LAMN_KeyText,     "S",
  3184.          LAMN_ItemText,     "A\0Save As...",
  3185.          LAMN_ItemText,     NM_BARLABEL,
  3186.          LAMN_ItemText,     "Print...",
  3187.           LAMN_KeyText,     "P",
  3188.          LAMN_ItemText,     NM_BARLABEL,
  3189.          LAMN_ItemText,     "Help...",
  3190.           LAMN_CommandText, "[Help]",
  3191.          LAMN_ItemText,     NM_BARLABEL,
  3192.          LAMN_ItemText,     "Quit...",
  3193.           LAMN_KeyText,     "Q",
  3194.         TAG_DONE
  3195.  
  3196.     Will create the following menu:
  3197.  
  3198.     +-------+
  3199.     |Project|
  3200.     +-------+------+
  3201.     |New         aN|
  3202.     |Open...     aO|
  3203.     |~~~~~~~~~~~~~~|
  3204.     |Save        aS|
  3205.     |Save As...  aA|
  3206.     |~~~~~~~~~~~~~~|
  3207.     |Print...    aP|
  3208.     |~~~~~~~~~~~~~~|
  3209.     |Help... [Help]|
  3210.     |~~~~~~~~~~~~~~|
  3211.     |Quit...     aQ|
  3212.     +--------------+
  3213.  
  3214.    NOTES
  3215.     You may freely add, remove, spindle & mutilate the contents of the
  3216.     menu strip created, just don't trash or disconnect the base menu
  3217.     entry this routine creates as all menu memory tracking data is
  3218.     connected to it.
  3219.  
  3220.    SEE ALSO
  3221.     gtlayout.library/LT_DisposeMenu
  3222.     gtlayout.library/LT_FindCommandItem
  3223.     gtlayout.library/LT_GetMenuItem
  3224.     gtlayout.library/LT_LayoutMenuA
  3225.     gtlayout.library/LT_MenuControlTagList
  3226.     gtlayout.library/LT_NewMenuTemplate
  3227.     intuition.library/SetMenuStrip
  3228.  
  3229. gtlayout.library/LT_NewMenuTemplate       gtlayout.library/LT_NewMenuTemplate
  3230.  
  3231.    NAME
  3232.     LT_NewMenuTemplate -- Allocate and layout menu items (V11)
  3233.  
  3234.    SYNOPSIS
  3235.     Menu = LT_NewMenuTemplate(Screen,TextAttr,AmigaGlyph,CheckmarkGlyph,
  3236.      D0                         A0      A1        A2           A3
  3237.  
  3238.                               Error,MenuTemplate);
  3239.                                 D0      D1
  3240.  
  3241.     struct Menu *LT_NewMenuTemplate(struct Screen *,struct TextAttr *,
  3242.                                     struct Image *,struct Image *,
  3243.                                     LONG *,struct NewMenu *);
  3244.  
  3245.    FUNCTION
  3246.     Allocates Menus and MenuItems similar to LT_LayoutMenus().
  3247.  
  3248.     As of v18 this routine will validate menu mutual exclusion
  3249.     information.
  3250.  
  3251.    INPUTS
  3252.     Screen - Pointer to the screen the menu will appear on. This
  3253.         parameter is required and must not be omitted.
  3254.  
  3255.     TextAttr - Pointer to the TextAttr that should be used to
  3256.         layout the menus. If this parameter is omitted,
  3257.         Screen->Font will be used instead.
  3258.  
  3259.     AmigaGlyph - Pointer to the Image to use as the Amiga glyph.
  3260.         This parameter may be omitted.
  3261.  
  3262.             NOTE: Ignored by intuition.library v37 and below.
  3263.  
  3264.     CheckmarkGlyph - Pointer to the Image to use as the checkmark
  3265.         glyph. This parameter may be omitted.
  3266.  
  3267.     Error - Pointer to receive error code in case the menu
  3268.         creation or layout process fails. This parameter
  3269.         may be omitted.
  3270.  
  3271.     MenuTemplate - Pointer to a series of NewMenu structures,
  3272.         just as you would pass to
  3273.         gtlayout.library/LT_LayoutMenuA.
  3274.  
  3275.    RESULT
  3276.     Menu - Pointer to Menu structure, ready to pass to
  3277.         SetMenuStrip(), NULL on failure.
  3278.  
  3279.    NOTES
  3280.     The menu created by this function cannot be used with the
  3281.     routines LT_MenuControlTagList, LT_FindMenuCommand and
  3282.     LT_GetMenuItem.
  3283.  
  3284.     You may freely add, remove, spindle & mutilate the contents of the
  3285.     menu strip created, just don't trash or disconnect the base menu
  3286.     entry this routine creates as all menu memory tracking data is
  3287.     connected with it.
  3288.  
  3289.    SEE ALSO
  3290.     gtlayout.library/LT_DisposeMenu
  3291.     gtlayout.library/LT_LayoutMenuA
  3292.     gtlayout.library/LT_NewMenuTagList
  3293.     intuition.library/SetMenuStrip
  3294.  
  3295. gtlayout.library/LT_PressButton               gtlayout.library/LT_PressButton
  3296.  
  3297.    NAME
  3298.     LT_PressButton -- Highlight a button so it looks as if the user
  3299.                       has selected it.
  3300.  
  3301.    SYNOPSIS
  3302.     LT_PressButton(Handle,ID);
  3303.                       A0  D0
  3304.  
  3305.     VOID LT_PressButton(LayoutHandle *,LONG);
  3306.  
  3307.    FUNCTION
  3308.     You can provide visual feedback for BUTTON_KIND objects by calling
  3309.     this routine. They will briefly appear to be selected and then
  3310.     fall back to their original states.
  3311.  
  3312.    INPUTS
  3313.     Handle - Pointer to LayoutHandle structure
  3314.  
  3315.     ID - ID of button object to highlight
  3316.  
  3317.    RESULT
  3318.     none
  3319.  
  3320. gtlayout.library/LT_RebuildTagList         gtlayout.library/LT_RebuildTagList
  3321.  
  3322.    NAME
  3323.     LT_RebuildTagList -- Rebuild the user interface after modifying it.
  3324.  
  3325.    SYNOPSIS
  3326.     Success = LT_RebuildTagList(Handle,Clear,TagList);
  3327.        D0                         A0    D0     A1
  3328.  
  3329.     BOOL LT_RebuildTagList(LayoutHandle *,BOOL,struct TagItem *);
  3330.  
  3331.     Success = LT_RebuildTags(Handle,Clear,...);
  3332.  
  3333.     BOOL LT_RebuildTags(LayoutHandle *,BOOL,...);
  3334.  
  3335.    FUNCTION
  3336.     Certain aspects of the user interface can be changed at run time,
  3337.     such as button labels. This routine will let you rebuild the interface
  3338.     based upon the data supplied at creation time and your subsequent
  3339.     changes. Before you make any vital changes, it is recommended to
  3340.     lock the window using LT_LockWindow() in order to avoid clashes
  3341.     with the Intuition and GadTools subsystems.
  3342.  
  3343.    INPUTS
  3344.     Handle - Pointer to LayoutHandle structure.
  3345.  
  3346.     Clear - Pass in TRUE if you wish to have the window contents
  3347.         cleared before they are rebuild. This will introduce
  3348.         some visual hashing.
  3349.  
  3350.     TagList - Attributes controlling the layout process.
  3351.  
  3352.  
  3353.     Valid tags include:
  3354.  
  3355.     LAWN_Bounds (struct IBox *) - Boundaries in which the window
  3356.         should be centered.
  3357.  
  3358.     LAWN_ExtraWidth (LONG) - Extra space to add to the window
  3359.         width.
  3360.  
  3361.     LAWN_ExtraHeight (LONG) - Extra height to add to the window
  3362.         height.
  3363.  
  3364.    RESULT
  3365.     Success - TRUE indicates that the interface was rebuilt,
  3366.         FALSE indicates trouble; it is recommended to
  3367.         call LT_DeleteHandle() on your LayoutHandle as
  3368.         soon as possible as the previous operation may
  3369.         have left the user interface in an inoperable
  3370.         state.
  3371.  
  3372. gtlayout.library/LT_Refresh                       gtlayout.library/LT_Refresh
  3373.  
  3374.    NAME
  3375.     LT_Refresh -- Redraws the entire window contents.
  3376.  
  3377.    SYNOPSIS
  3378.     LT_Refresh(Handle)
  3379.                  A0
  3380.  
  3381.     VOID LT_Refresh(LayoutHandle *);
  3382.  
  3383.    FUNCTION
  3384.     Redraws the contents of the window, this includes both gadgets
  3385.     and imagery.
  3386.  
  3387.    INPUTS
  3388.     Handle - Pointer to a LayoutHandle structure.
  3389.  
  3390.    RESULT
  3391.     none
  3392.  
  3393.    SEE ALSO
  3394.        gadtools.library/GT_RefreshWindow
  3395.        intuition.library/RefreshGList
  3396.  
  3397. gtlayout.library/LT_ReplyIMsg                   gtlayout.library/LT_ReplyIMsg
  3398.  
  3399.    NAME
  3400.     LT_ReplyIMsg -- Dispose of an IntuiMessage received
  3401.  
  3402.    SYNOPSIS
  3403.     LT_ReplyIMsg(IntuiMessage);
  3404.                      A0
  3405.  
  3406.     VOID LT_ReplyIMsg(struct IntuiMessage *);
  3407.  
  3408.    FUNCTION
  3409.     This routine complements LT_GetIMsg().
  3410.  
  3411.    INPUTS
  3412.     IntuiMessage - Pointer to IntuiMessage structure,
  3413.         passing NULL is harmless.
  3414.  
  3415.    RESULT
  3416.     none
  3417.  
  3418.    NOTES
  3419.     Only pass IntuiMessages you received via LT_GetIMsg,
  3420.     or things will get tough.
  3421.  
  3422.    SEE ALSO
  3423.     gtlayout.library/LT_GetIMsg
  3424.  
  3425. gtlayout.library/LT_SetAttributesA         gtlayout.library/LT_SetAttributesA
  3426.  
  3427.    NAME
  3428.     LT_SetAttributesA -- Change object attributes
  3429.  
  3430.    SYNOPSIS
  3431.     LT_SetAttributesA(Handle,ID,Tags);
  3432.                         A0   D0  A1
  3433.  
  3434.     VOID LT_SetAttributes(LayoutHandle *,LONG,struct TagItem *);
  3435.  
  3436.     LT_SetAttributes(Handle,ID,...);
  3437.  
  3438.     VOID LT_SetAttributes(LayoutHandle *,LONG,...);
  3439.  
  3440.    FUNCTION
  3441.     This routine passes the tag item list it gets directly
  3442.     over to GT_SetGadgetAttrsA(), so any tag items valid for
  3443.     gadtools.library can be used here as well. Some filtering
  3444.     may be done in order to stop objects from getting redrawn
  3445.     if this is not absolutely necessary.
  3446.  
  3447.    INPUTS
  3448.     Handle - Pointer to LayoutHandle.
  3449.  
  3450.     ID - ID number of the object to change. This is the same value
  3451.         you passed via LA_ID to LT_New() when you created this object.
  3452.  
  3453.     Tags - Attributes controlling object states.
  3454.  
  3455.  
  3456.     All gadtools.library tags are allowed, but not all are supported.
  3457.     In addition to these tags a few additional tag values are
  3458.     supported:
  3459.  
  3460.     LAHN_AutoActivate (BOOL) - Set to TRUE if you want the interface
  3461.         to always keep a string gadget active if possible. Hitting
  3462.         the return key will then cause the next following string
  3463.         gadget to get activated, either cycling through all the
  3464.         string gadgets available or stopping at the next string
  3465.         gadget to have the LAST_LastGadget attribute set.
  3466.  
  3467.     LAHN_UserData (APTR) - Store user specific data in the
  3468.         LayoutHandle->UserData entry. (V9)
  3469.  
  3470.     LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
  3471.         events. (V13)
  3472.         Default: TRUE
  3473.  
  3474.     LAHN_LocaleHook (struct Hook *) - The hook to call when
  3475.         locale string IDs are to be mapped to strings. The
  3476.         hook function is called with the following parameters:
  3477.  
  3478.         String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
  3479.           D0                            A0                         A2
  3480.                           LONG ID)
  3481.                                A1
  3482.  
  3483.         The function is to look up the string associated with the ID
  3484.         passed in and return the string.
  3485.  
  3486.     LAHN_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
  3487.         of with LT_DeleteHandle() all variables maintained by the
  3488.         input handling code will be flushed. For example, if you
  3489.         would use the LA_STRPTR tag for STRING_KIND objects the
  3490.         last string gadget contents would be copied into the buffer
  3491.         pointed to by LA_STRPTR. If you do not want to use this
  3492.         feature, disable it with "LAHN_ExitFlush,FALSE". (V9)
  3493.         Default: TRUE
  3494.  
  3495.     GAUGE_KIND:
  3496.  
  3497.         LAGA_Percent (LONG) - Percentage of the gauge to fill.
  3498.  
  3499.         LAGA_InfoText (STRPTR) - Text to be printed within the
  3500.             gauge display, such as a percentage number.
  3501.  
  3502.     BOX_KIND:
  3503.  
  3504.         LABX_Index (LONG) - The number of the line to change, this
  3505.             tag works in conjunction with the LABX_Text tag.
  3506.  
  3507.         LABX_Text (STRPTR) - The text to put into the line indicated
  3508.             by the LABX_Index tag.
  3509.             As of v26 the LABX_Index tag may be omitted, the library
  3510.             will then assume the line index will be 0.
  3511.  
  3512.         LABX_Lines (STRPTR *) - The text to set for the box contents,
  3513.             terminate the text array with NULL.
  3514.  
  3515.     HORIZONTAL_KIND:
  3516.     VERTICAL_KIND:
  3517.  
  3518.         LAGR_ActivePage (LONG) - Index number of page to display
  3519.             within the group.
  3520.  
  3521.                 NOTE: requires that this group was created
  3522.                     with the LAGR_ActivePage attribute set.
  3523.  
  3524.     INTEGER_KIND:
  3525.  
  3526.         LAIN_Min (LONG) - Minimum allowed value for this
  3527.             object.
  3528.  
  3529.         LAIN_Max (LONG) - Maximum allowed value for this
  3530.             object.
  3531.  
  3532.     LISTVIEW_KIND:
  3533.  
  3534.         LALV_Selected (LONG) - Combines GTLV_Selected and
  3535.             GTLV_Top (for Kickstart V37) or GTLV_MakeVisible
  3536.             (for Kickstart V39 and greater). This means, the
  3537.             list display will be changed in order to show
  3538.             the item to be selected. (V34)
  3539.  
  3540.     PASSWORD_KIND:
  3541.  
  3542.         LAPW_String (STRPTR) - Secret text to use
  3543.  
  3544.     POPUP_KIND
  3545.  
  3546.         LAPU_Labels (STRPTR *) - To block access to the popup
  3547.             menu, for example before you free the current list
  3548.             of labels, you can pass ~0 as the list parameter. (V25)
  3549.  
  3550.     STRING_KIND:
  3551.  
  3552.         LAST_CursorPosition (LONG) - Repositions the cursor,
  3553.             pass -1 to move it to the end of the string. (V7)
  3554.  
  3555.     TAPEDECK_KIND:
  3556.  
  3557.         LATD_Pressed (BOOL) - TRUE to make this button shown
  3558.             as pressed, FALSE to show it in depressed state.
  3559.  
  3560.     BOOPSI_KIND:
  3561.  
  3562.         All tags are passed straight through to SetGadgetAttrs(..).
  3563.  
  3564.     All objects:
  3565.  
  3566.         LA_LabelText (STRPTR) - New gadget label text to use.
  3567.  
  3568.         LA_LabelID (LONG) - Locale text ID to use for this object.
  3569.  
  3570.    RESULT
  3571.     none
  3572.  
  3573.    SEE ALSO
  3574.     gadtools.library/GT_SetGadgetAttrsA()
  3575.     intuition.library/SetGadgetAttrsA
  3576.  
  3577. gtlayout.library/LT_ShowWindow                 gtlayout.library/LT_ShowWindow
  3578.  
  3579.    NAME
  3580.     LT_ShowWindow -- Make a window visible
  3581.  
  3582.    SYNOPSIS
  3583.     LT_ShowWindow(Handle,Activate);
  3584.                     A0      A1
  3585.  
  3586.     VOID LT_ShowWindow(LayoutHandle *,BOOL);
  3587.  
  3588.    FUNCTION
  3589.     The window attached to a LayoutHandle is made visible, this
  3590.     involves bringing it to the front, bringing the screen to
  3591.     the front the window resides on, unzooming the window and
  3592.     also moving the visible part of an autoscrolling screen.
  3593.  
  3594.    INPUTS
  3595.     Window - Pointer to Window structure.
  3596.  
  3597.     Activate - If TRUE the window will be activated as soon
  3598.         as it has been brought to the front.
  3599.  
  3600.    RESULT
  3601.     none
  3602.  
  3603.    NOTES
  3604.     The arguments are passed in A0 and A1, this is *not* a
  3605.     typo.
  3606.  
  3607.    BUGS
  3608.     In revisions earlier than v21 this routine consistently
  3609.     failed to reliably unzip a window in zoomed state. This
  3610.     could cause the calling application to wait for about
  3611.     five seconds before continuing execution.
  3612.  
  3613.    SEE ALSO
  3614.     intuition.library/MoveScreen
  3615.     intuition.library/ScreenPosition
  3616.     intuition.library/ZipWindow
  3617.  
  3618. gtlayout.library/LT_UnlockWindow             gtlayout.library/LT_UnlockWindow
  3619.  
  3620.    NAME
  3621.     LT_UnlockWindow -- The complement to LT_LockWindow().
  3622.  
  3623.    SYNOPSIS
  3624.     LT_UnlockWindow(Window);
  3625.                       A0
  3626.  
  3627.     VOID LT_UnlockWindow(struct Window *);
  3628.  
  3629.    FUNCTION
  3630.     This routine unlocks a window locked using LT_LockWindow, freeing
  3631.     allocated memory, restoring the window characteristics to their
  3632.     original values.
  3633.  
  3634.    INPUTS
  3635.     Window - Pointer to window structure; passing NULL is harmless.
  3636.  
  3637.    RESULT
  3638.     none
  3639.  
  3640.    SEE ALSO
  3641.     gtlayout.library/LT_LockWindow
  3642.  
  3643. gtlayout.library/LT_UpdateStrings           gtlayout.library/LT_UpdateStrings
  3644.  
  3645.    NAME
  3646.     LT_UpdateStrings -- Make sure all visible string buffer contents
  3647.                         get written into storage (v9).
  3648.  
  3649.    SYNOPSIS
  3650.     LT_UpdateStrings(LayoutHandle);
  3651.                             A0
  3652.  
  3653.     VOID LT_UpdateStrings(struct LayoutHandle *);
  3654.  
  3655.    FUNCTION
  3656.     The user can terminate input into a string gadget or an object
  3657.     derived from a string gadget by various means. They all have
  3658.     in common that the application receives no notification that
  3659.     the string gadget contents have changed. This is particularly
  3660.     nasty with objects which make use of LA_STRPTR or other
  3661.     tags. Using LT_UpdateStrings() you can force all visible string
  3662.     gadget objects to hand over their contents to the internal
  3663.     buffers. Do this before you eventually exit your input loop.
  3664.  
  3665.    INPUTS
  3666.     LayoutHandle - Pointer to LayoutHandle structure.
  3667.  
  3668.    RESULT
  3669.     none
  3670.  
  3671.